Cài đặt và sử dụng — System Settings

Tổng quan

@digiforce-nc/plugin-system-settings quản lý các cài đặt hệ thống toàn cục: tên ứng dụng, logo, favicon, banner đăng nhập, ngôn ngữ mặc định, và nhiều tùy chọn branding khác. Plugin thường được bật sẵn khi cài đặt Digiforce.

Bước 1: Kiểm tra Plugin

Plugin thường đã được kích hoạt sẵn. Kiểm tra trong Settings → Plugin Manager.

Khi cài đặt lần đầu (install), plugin tự động:

1. Upload ảnh logo, squareLogo, favicon, banner mặc định qua plugin-file-manager
2. Tạo bản ghi systemSettings với giá trị mặc định
3. Đặt appLang theo tham số CLI --lang hoặc biến môi trường INIT_APP_LANG (mặc định: en-US)

Bước 2: Cấu hình qua giao diện

Vào Settings → System Settings và thay đổi:

Branding

Cài đặt	Mô tả	Khuyến nghị
Application title	Tên ứng dụng (hiển thị trên header và tab trình duyệt)	Hỗ trợ i18n template
Logo	Logo chính — hiển thị trên header, trang đăng nhập	PNG/SVG, nền trong suốt, ~200×50px
Square Logo	Logo vuông — dùng cho mobile icon, favicon fallback	PNG, 128×128px
Favicon	Biểu tượng tab trình duyệt	ICO/PNG, 32×32px hoặc 16×16px
Banner	Banner trang đăng nhập	SVG/PNG, kích thước lớn
Loader	Animation loading khi khởi động ứng dụng	GIF/SVG
Show logo only	Ẩn title, chỉ hiển thị logo trên header	Checkbox
Brand HTML	HTML hiển thị ở footer (VD: "Powered by...")	Hỗ trợ HTML + link

Ngôn ngữ

Cài đặt	Mô tả
Default language	Ngôn ngữ mặc định cho người dùng mới
Enabled languages	Danh sách ngôn ngữ hiển thị trong bộ chọn ngôn ngữ

Bảo mật

Cài đặt	Mặc định	Mô tả
Allow sign up	true	Cho phép đăng ký tài khoản mới
SMS authentication	false	Bật xác thực bằng SMS

Giao diện

Cài đặt	Mặc định	Mô tả
Header style	appLauncher	Kiểu hiển thị header

Cấu hình qua API

Đọc cấu hình (public)

GET /api/systemSettings:get

Response trả về tất cả settings bao gồm logo/favicon/banner URLs. Endpoint này public — trang đăng nhập sử dụng để hiển thị branding.

Lưu ý: Field title trong response đã được render qua renderJsonTemplate() — hỗ trợ biến môi trường. Field raw_title chứa giá trị gốc.

Cập nhật cấu hình (admin)

PUT /api/systemSettings:put
Content-Type: application/json

{
  "raw_title": "My Application",
  "appLang": "vi-VN",
  "enabledLanguages": ["vi-VN", "en-US"],
  "allowSignUp": false,
  "brand": "Powered by <a href='https://digiforce.vn'>Digiforce</a>",
  "headerStyle": "appLauncher"
}

Lưu ý: Khi cập nhật title qua API, sử dụng field raw_title (không phải title). Server sẽ lưu raw_title vào DB field title.

Luồng hoạt động

Biến môi trường

Biến	Mô tả
INIT_APP_LANG	Ngôn ngữ mặc định khi cài đặt lần đầu (mặc định: en-US)

Cũng có thể đặt qua CLI: digiforce install --lang vi-VN

ACL và bảo vệ dữ liệu

• Bản ghi systemSettings có ID = 1 không thể xóa (fixedParams: id.$ne: 1 cho action destroy)
• systemSettings:get là public — ai cũng đọc được
• systemSettings:put yêu cầu quyền admin (ACL snippet)

Lưu ý quan trọng

• Thay đổi có hiệu lực ngay lập tức (một số cần refresh trang)
• Logo/favicon/banner lưu dưới dạng belongsTo attachments — quản lý qua plugin-file-manager
• Field title hỗ trợ i18n template — có thể dùng biến môi trường hoặc translation key
• Settings lưu trong Database → không bị mất khi cập nhật code
• Chỉ có 1 bản ghi systemSettings (ID = 1) — không thể tạo thêm