DataSense Document

DataSense Framework v5.4: Tài liệu Hướng dẫn

Biến Blogger thành nền tảng Web App doanh nghiệp: Serverless, Offline-first, Excel-like UI.

Mục lục nhanh:
  1. Cài đặt Môi trường
  2. Cấu hình API & Kết nối (api)
  3. Cấu hình Giao diện (ui)
  4. Cấu hình Hệ thống (sys)
  5. Định nghĩa Cột dữ liệu (columns)
  6. Hàm tính toán & Logic nâng cao

1. Cài đặt Môi trường

Để bắt đầu, bạn cần dán mã nguồn Core Engine vào Blogger. Sau đó, mỗi ứng dụng (App) sẽ được đăng ký thông qua hàm registerBloggerApp.

💡 Mẹo: Hãy dán mã Core Engine vào một trang tĩnh (Page) hoặc Layout Widget để dùng chung cho toàn bộ blog, hoặc dán trực tiếp vào bài viết nếu chỉ dùng cho bài đó.

2. Cấu hình API (config.api)

Đây là "trái tim" kết nối App với Google Sheets. Bạn cần Deploy Google Apps Script dưới dạng Web App và lấy URL.

Tham số Giá trị / Kiểu Giải thích chi tiết
url Required String (URL) Đường dẫn Web App của Google Script (kết thúc bằng /exec).
Lưu ý: Phải set quyền truy cập là "Anyone" (Bất kỳ ai).
appName Required String (No space) Tên định danh ứng dụng (viết liền không dấu, vd: 'KhoHang').
Dùng để tạo tên Sheet trên Google Spreadsheet và làm khóa lưu Cache.
mode Required 'SHARED' | 'USER_SPECIFIC'
  • SHARED: Tất cả nhân viên dùng chung 1 Sheet. (Tên Sheet = appName). Phù hợp: Kho chung, Nhật ký máy.
  • USER_SPECIFIC: Mỗi nhân viên có 1 Sheet riêng. (Tên Sheet = appName_username). Phù hợp: KPI cá nhân, Chấm công.

3. Cấu hình Giao diện (config.ui)

Quy định màu sắc, tab chức năng và điều hướng.

Tham số Giải thích
primaryColor Mã màu HEX (vd: '#009688'). Màu chủ đạo của nút bấm, tab đang chọn.
rowClickAction Hành động khi bấm vào một dòng dữ liệu.
Cấu trúc: { type: 'switchTab', target: 'tab_id' }
Ví dụ: Bấm dòng dữ liệu để chuyển sang tab Biểu đồ/Chi tiết.
tabs Mảng chứa các Tab chức năng. Mỗi tab gồm:
  • id: Định danh tab.
  • label: Tên hiển thị (có thể dùng Emoji).
  • module: Tên Module xử lý (DataModule, SearchModule, ChartModule, hoặc Plugin riêng).
  • default: true nếu muốn tab này mở đầu tiên.
  • hidden: true để ẩn tab (dùng cho các tab phụ chỉ mở khi click).
  • showFab: true để hiện nút tròn thêm mới (+).

4. Cấu hình Hệ thống (config.sys)

Điều khiển hành vi cốt lõi của ứng dụng như lọc, sắp xếp, ngôn ngữ.

Tham số Giá trị Chi tiết
lang 'VI' | 'EN' Ngôn ngữ hiển thị các thông báo hệ thống (Lỗi, Thành công, Đang tải...).
daysToLoad Number (vd: 30) Số ngày quá khứ sẽ tải dữ liệu về khi khởi động. Giúp App nhẹ hơn thay vì tải toàn bộ lịch sử 10 năm.
allowRegister Boolean true: Cho phép người dùng đăng ký tài khoản mới.
false: Ẩn nút đăng ký, chỉ cho phép đăng nhập (Bảo mật).
filterType 'date' | 'text' Kiểu bộ lọc mặc định ở Tab Nhập liệu:
- date: Hiện ô chọn ngày tháng.
- text: Hiện ô nhập từ khóa tìm kiếm nhanh.
filterField String | Array Tên cột sẽ bị ảnh hưởng bởi bộ lọc cục bộ.
Vd: ['date', 'lotNo'] -> Khi gõ vào ô lọc, nó sẽ tìm trong cả cột Ngày và LotNo.
sortOrder Quan trọng Array Quy định thứ tự sắp xếp mặc định. Hỗ trợ dấu - để giảm dần.
Vd: ['-date', '-time', 'line']
(Nghĩa là: Ngày mới nhất -> Giờ mới nhất -> Line từ nhỏ đến lớn).

5. Cấu hình Cột (config.columns)

Đây là phần quan trọng nhất, định nghĩa Schema dữ liệu.

columns: [
  { field: "id", visible: false }, // Bắt buộc
  { field: "prod_date", header: "Ngày SX", type: "date", default: "CURRENT_DATE" },
  { field: "qty", header: "SL", type: "integer", required: true }
]
Thuộc tính Mô tả & Chức năng
field Tên cột dữ liệu (Key). Viết liền không dấu, không khoảng trắng (vd: userName).
header Tiêu đề cột hiển thị trên bảng (vd: "Người dùng").
type Kiểu dữ liệu:
  • text: Chuỗi ký tự (Tự động viết hoa).
  • integer: Số nguyên (Tự động format 1,000).
  • decimal: Số thập phân (1,000.00).
  • money: Tiền tệ.
  • date: Ngày (YYYY-MM-DD).
  • time: Giờ (HH:mm) - Có hỗ trợ sắp xếp Ca Đêm.
  • checkbox: Ô chọn (True/False).
  • select: Menu thả xuống (kết hợp với options: [...]).
visible false để ẩn cột khỏi bảng (nhưng dữ liệu vẫn được tải về).
required true bắt buộc nhập, không được để trống khi lưu.
readonly true chỉ xem, không cho sửa (thường dùng cho cột Thành tiền, User...).
sticky true giữ lại giá trị vừa nhập cho lần nhập tiếp theo (Rất tiện cho nhập liệu hàng loạt).
unique true kiểm tra trùng lặp dữ liệu (vd: Mã Barcode không được trùng).
autoComplete true tự động gợi ý dữ liệu cũ khi gõ (như Google Search).
isScan true cho phép nhận dữ liệu từ Camera Scanner (QR/Barcode).
default Giá trị mặc định khi tạo mới. Hỗ trợ các biến hệ thống:
"CURRENT_DATE", "CURRENT_TIME", "CURRENT_USER".
value Công thức tính toán tự động (Xem mục 6).

6. Hàm tính toán & Logic nâng cao

A. Công thức (Formula)

Đặt trong thuộc tính value của cột. Hệ thống tự động tính toán lại khi các cột phụ thuộc thay đổi.

Hàm Cú pháp Ví dụ thực tế
PRODUCT Nhân các số "PRODUCT('so_luong', 'don_gia')" -> Thành tiền.
SUM Cộng các số "SUM('phi_ship', 'gia_goc')" -> Tổng tiền.
SUBTRACT Trừ (Số đầu trừ các số sau) "SUBTRACT('tong_thu', 'chi_phi')" -> Lợi nhuận.
LOOKUP Dò tìm giá trị (VLOOKUP) "LOOKUP('ma_sp')"
Tự động tìm giá trị cũ gần nhất của cột hiện tại dựa trên 'ma_sp'. Vd: Nhập mã A tự ra tên Bánh.
IF_EMPTY Lấy giá trị dự phòng "IF_EMPTY('nguoi_duyet', 'nguoi_lap')" -> Nếu chưa duyệt thì lấy tên người lập.

B. Logic Ca Đêm (Night Shift)

Để giải quyết vấn đề sắp xếp giờ qua đêm (ví dụ 1h sáng là thuộc ca đêm hôm trước, phải xếp sau 23h), hãy thêm cấu hình sau:

logic: {
  production: {
    nightShiftCutoff: 6 // Giờ cắt ca là 6:00 sáng
  }
}

Khi đó: 01:00, 02:00... 05:59 sẽ được hệ thống hiểu là 25:00, 26:00... và xếp sau 23:00.

⚠️ Lưu ý: Mọi thay đổi trong Config chỉ áp dụng sau khi bạn tải lại trang (F5). Dữ liệu cũ đã lưu trên Sheet sẽ không bị ảnh hưởng.