Tài Liệu Cấu Hình DataSense

Tài Liệu Cấu Hình DataSense

Từ điển toàn tập các thuộc tính khai báo để xây dựng App con trên nền tảng DataSense Framework v70+

Để khởi tạo một ứng dụng con mới, bạn cần định nghĩa một Object cấu hình và đưa vào mảng APP_CONFIGS. Object này bao gồm 4 phần chính: Khai báo cấp độ App, Giao diện (ui), Cấu hình Hệ thống (sys), và Cấu trúc Cột (columns).

Phần 1: Khai Báo Cấp Độ App (App Level)

Thuộc tính Kiểu dữ liệu Mô tả chi tiết
id Bắt buộc String Định danh duy nhất của App (Viết liền không dấu, VD: 'QuanLyThuChi'). Dùng để đặt tên Thư mục và File trên Google Drive.
name Bắt buộc String Tên hiển thị của App trên giao diện Dropdown (Có thể dùng Emoji, VD: '📅 QUẢN LÝ THU CHI').
storageMode Bắt buộc String Chế độ lưu trữ:
- 'SHARED': Tất cả người dùng ghi chung vào 1 file Spreadsheet.
- 'USER_SPECIFIC': Hệ thống tự động tách mỗi người dùng 1 file Spreadsheet riêng biệt.

Phần 2: Khai Báo Giao Diện (ui)

Đối tượng ui chứa cấu hình màu sắc và các tab chức năng hiển thị trên màn hình.

Thuộc tính Kiểu dữ liệu Mô tả chi tiết
primaryColor Bắt buộc String (HEX) Mã màu chủ đạo của App (VD: '#0B5599').
rowClickAction Tùy chọn Object Hành động khi click vào 1 dòng dữ liệu. VD: { type: 'switchTab', target: 'drawing' } để tự động chuyển sang tab Bản vẽ.
tabs Bắt buộc Array [Objects] Danh sách các Tab chức năng. Các tham số của 1 tab bao gồm:

- id: ID của tab.
- label: Tên hiển thị trên menu.
- module: Lõi render (VD: 'DataModule', 'SearchModule', 'StatsModule', 'NativeChartModule', 'PosModule', 'FormModule').
- default: Cắm cờ true để mở tab này làm mặc định.
- showFab: Hiển thị nút (+) Thêm mới.
- filterType: Ghi đè loại bộ lọc (text, select, date, month, year, week).
- filterColumn: Ghi đè cột dùng để lọc (Nếu bỏ trống sẽ lấy theo partitionField).
- chartSettings: Dùng cho NativeChartModule (VD: { type: 'pie', labelField: 'group', valueField: 'expense' }).
- posConfig: Dùng cho PosModule (Cấu hình liên kết App, quét mã vạch).

Phần 3: Khai Báo Hệ Thống (sys)

Đối tượng sys thiết lập các cơ chế phân mảnh dữ liệu, đồng bộ, và cấp quyền truy cập.

Thuộc tính Kiểu dữ liệu Mô tả chi tiết
lang Bắt buộc String Ngôn ngữ hiển thị hệ thống: 'VI' hoặc 'EN'.
partitionField Bắt buộc String Cột cốt lõi của hệ thống. Đảm nhiệm 3 vai trò:
1. Phân mảnh (Sharding) Sheet trên Google Drive.
2. Là cột được dùng làm Bộ lọc (Filter) mặc định trên DataModule.
3. Là cột dùng để Gộp nhóm (Subtotal) trên SearchModule.
sortOrder Tùy chọn Array [String] Mảng quy định thứ tự sắp xếp đa cấp. Thêm dấu - phía trước để sắp xếp giảm dần.
VD: ["-date", "time"] (Ngày mới nhất lên trên, sau đó xếp theo giờ).
Lưu ý: Phần tử đầu tiên của mảng này sẽ tự động được dùng làm cột Gộp nhóm (Subtotal) cho Tab Data.
crossApps Tùy chọn Array [String] Khai báo ID của các App khác cần được tải ngầm về RAM để phục vụ tính toán chéo (Cross-App Calculation).
isPublic / allowRegister Boolean Cho phép truy cập không cần đăng nhập / Cho phép tự do đăng ký tài khoản.
filterField / sortField Đã Khai Tử - Không còn sử dụng. Logic đã được tối ưu hóa gộp chung vào partitionField và sortOrder. (Chỉ được phép dùng filterField: "ALL" nếu muốn ô tìm kiếm DataModule quét qua mọi cột).

Phần 4: Khai Báo Cột Dữ Liệu (columns)

Mảng columns định nghĩa cấu trúc dữ liệu, hiển thị, và các ràng buộc (Validation) cho từng trường.

Thuộc tính Mô tả chi tiết & Ví dụ
field & header field: Tên biến lưu vào Database (Không dấu, không khoảng trắng).
header: Tiêu đề hiển thị trên bảng.
type Kiểu dữ liệu hỗ trợ phong phú:
Cơ bản: text, text_upper, longtext, checkbox, select
Thời gian: date, time, shiftDate, month, year, week
Số liệu: integer, decimal, money, percent
Nâng cao: composite, gps, phone, image, tag
Đặc thù (App): line, lotNo, partNo, awFilm, frame, wh, mark
Các Cờ Trạng Thái (Boolean) required: true (Bắt buộc nhập)
readonly: true (Chỉ đọc, không cho sửa)
hidden: true (Ẩn trên bảng dữ liệu, nhưng vẫn có trong Form sửa)
visible: false (Khóa hoàn toàn khỏi UI giao diện)
showTotal: true (Vẽ huy hiệu tính tổng Σ ở tiêu đề bảng)
isSearch: true (Đưa vào radar quét của tab Tra cứu nhanh)
isScan: true (Gắn nút Camera bật máy quét mã vạch cho ô này)
Điều Hướng (Navigation) sticky: true (Lưu lại giá trị cuối cùng vừa nhập cho lần nhập sau). Hỗ trợ Mảng để theo dõi chéo: sticky: ['time', 'line'] (Chỉ xóa ô này khi ô Time hoặc Line bị xóa).
skipOnNav: true (Bỏ qua ô này khi người dùng bấm phím Enter/Tab nếu ô đã có dữ liệu).
autoComplete Tính năng gợi ý thông minh. Xổ xuống như Select Box nhưng cho phép gõ thêm chữ mới.
- Khai báo Boolean: autoComplete: true (Tự học 100% từ lịch sử nhập liệu).
- Khai báo Mảng (Dữ liệu mồi): autoComplete: ["Tiền mặt", "Chuyển khoản"]
default Giá trị mặc định khi tạo dòng mới.
Hỗ trợ các hằng số hệ thống: 'CURRENT_VALUE' (Ngày/Giờ hiện tại), 'CURRENT_USER' (Tên người đăng nhập), 'HISTORICAL' (Truy tìm giá trị của dòng sát sườn nhất trong quá khứ).
value Hàm tính toán thời gian thực (Formula). Nếu ô không bị readonly, người dùng gõ tay sẽ làm giá trị chuyển sang màu Cam cảnh báo.
Hỗ trợ: "LOOKUP(ColA, ColB)", "PRODUCT('qty','coeff')", "SUBTRACT('tonDau', 'daBan')", "CONCAT('part','layer')"...

Ví dụ Minh Họa Cấu Hình

const APP_CONFIGS = {}; APP_CONFIGS.QuanLyThuChi = { id: 'QuanLyThuChi', name: '📅 QUẢN LÝ THU CHI', storageMode: 'SHARED', ui: { primaryColor: "#0B5599", tabs: [ { id: "data", label: "📝 NHẬP LIỆU", module: "DataModule", default: true, showFab: true }, { id: "dashboard", label: "💼 BÁO CÁO", module: "FinanceStatsModule" }, { id: "chart", label: "📈 BIỂU ĐỒ", module: "NativeChartModule", chartSettings: { type: 'pie', labelField: 'group', valueField: 'expense' } } ] }, sys: { lang: 'VI', partitionField: "event", // Cột cốt lõi dùng để phân mảnh & Lọc sortOrder: ["-date"], // Xếp ngày mới nhất lên trên allowRegister: false, isPublic: true }, columns: [ { field: "date", header: "Ngày", type: "date", default: "CURRENT_VALUE", required: true }, { field: "event", header: "Sự kiện", type: "text_upper", required: true, autoComplete: true, default: "HISTORICAL" }, { field: "person", header: "Đối tượng", type: "text", required: true, isSearch: true }, { field: "group", header: "Nhóm", type: "tag", required: true, autoComplete: true, default: "HISTORICAL" }, { field: "income", header: "Thu (+)", type: "money", showTotal: true }, { field: "expense", header: "Chi (-)", type: "money", showTotal: true }, { field: "paymentMethod", header: "Hình thức", type: "text", required: true, sticky: true, autoComplete: ["Chuyển khoản", "Tiền mặt"] }, { field: "note", header: "Ghi chú", type: "text", isSearch: true } ] };