@digiforce-nc/cli


Package	`@digiforce-nc/cli`
Depends on	`@digiforce-nc/app`

1) Tổng quan

@digiforce-nc/cli cung cấp lệnh digiforce - công cụ dòng lệnh chính để quản lý vòng đời ứng dụng Digiforce: khởi động, cài đặt, nâng cấp, quản lý plugin, và phát triển.

Vai trò

CLI là entry point duy nhất cho mọi tương tác với Digiforce từ terminal. Nó khởi tạo environment, tạo Application instance, rồi delegate sang các command handler tương ứng.

2) Bảng lệnh chính

Lifecycle commands

Lệnh	Mô tả	Ví dụ
`digiforce dev`	Khởi động development server với hot reload	`digiforce dev --port 3000`
`digiforce start`	Khởi động production server	`digiforce start -d`
`digiforce install`	Cài đặt ứng dụng: tạo bảng, seed dữ liệu	`digiforce install`
`digiforce upgrade`	Chạy migration và nâng cấp hệ thống	`digiforce upgrade`

Plugin management (`pm`)

Lệnh	Mô tả	Ví dụ
`digiforce pm add <plugin>`	Thêm plugin vào hệ thống	`digiforce pm add @digiforce-nc/plugin-audit-logs`
`digiforce pm enable <plugin>`	Kích hoạt plugin	`digiforce pm enable audit-logs`
`digiforce pm disable <plugin>`	Vô hiệu hóa plugin	`digiforce pm disable audit-logs`
`digiforce pm remove <plugin>`	Gỡ bỏ plugin	`digiforce pm remove audit-logs`
`digiforce pm list`	Liệt kê tất cả plugin và trạng thái	`digiforce pm list`

Schema export / import (`schema`)

Lệnh	Mô tả	Ví dụ
`digiforce schema -l`	Liệt kê menu tree (UID, title, type)	`digiforce schema -l`
`digiforce schema -i <uid> -p <plugin>`	Export một route theo UID vào plugin	`digiforce schema -i abc123 -p @digiforce/plugin-my-app`
`digiforce schema -a -p <plugin>`	Export tất cả root menu items	`digiforce schema -a -p @digiforce/plugin-my-app`
`digiforce schema -a -r -p <plugin>`	Export đệ quy (bao gồm children của group)	`digiforce schema -a -r -p @digiforce/plugin-my-app`
`digiforce schema -A import -b <path>`	Import schemas từ thư mục plugin	`digiforce schema -A import -b packages/plugins/@digiforce/plugin-my-app/src`

Options đầy đủ:

Option	Mô tả
`-l, --list`	In cây menu ra stdout
`-i, --uid <schema-uid>`	Schema UID cần export (chỉ khớp mục menu gốc)
`-a, --all`	Export tất cả root menu items
`-f, --force`	Ghi đè file `.ts` nếu đã tồn tại
`-p, --plugin <name>`	Tên plugin đích — file ghi vào `<plugin>/src/server/schemas/`
`-r, --recursive`	Đệ quy export children khi route là group
`-A, --action <action>`	`export` (mặc định) hoặc `import`
`-b, --base-path <path>`	Thư mục gốc cho import (cần có `server/schemas/` bên trong)

Trước khi chạy

Cần database đã cài đặt và ứng dụng kết nối được tới DB (giống các lệnh digiforce có xác thực). Khi export, hệ thống khởi động ứng dụng để đọc menu và schema từ dữ liệu thật.

Format file export:

Mỗi file .ts sinh ra có dạng:

typescript

export default {
  target: 'digiforce-admin-menu',
  position: 'beforeEnd',
  route: { type: 'page', schemaUid: '...', title: '...', icon: '...' },
  schema: { /* Formily JSON Schema */ },
  widgets: [ /* khi trang uiPage: widget trang và các tab */ ],
};

Field	Khi nào có	Mô tả
`route`	Luôn có	Metadata route (type, title, icon, schemaUid). Với group: không bao gồm `children` (con export bằng `-r`).
`schema`	Luôn có	Cấu trúc Formily của trang (đã mở rộng đủ khối con; block template đã gắn nội dung thật).
`widgets`	Khi trang là `uiPage`	Danh sách widget: phần tử đầu là khối trang, các phần tử sau là khối từng tab con (nếu có).

Cấu trúc thư mục khi export đệ quy (-r):

<plugin>/src/server/schemas/
├── rootGroupUid.ts              # Group route
├── rootGroupUid.d/
│   ├── childPageUid.ts          # Child page
│   └── childGroupUid.ts         # Nested group
│       └── childGroupUid.d/
│           └── grandchildUid.ts # Grandchild
└── anotherRootUid.ts

Import:

Lệnh digiforce schema -A import -b <basePath> đọc thư mục <basePath>/server/schemas/, nạp từng file .ts hoặc .js, và các thư mục con dạng <schemaUid>.d/ (cùng cấu trúc với lúc export). Menu, schema giao diện và widget được ghi vào database trong một lần xử lý; ứng dụng cần có plugin lưu trữ schema (plugin-ui-schema-storage).

3) Flow xử lý lệnh

4) Utility functions

`initEnv()`

Đọc và merge các file environment theo thứ tự ưu tiên:

typescript

// Thứ tự load (sau override trước):
// 1. .env               - cấu hình mặc định
// 2. .env.local          - override cục bộ (git-ignored)
// 3. .env.[NODE_ENV]     - theo môi trường (development, production)
// 4. .env.[NODE_ENV].local

initEnv();
// Sau khi gọi, process.env chứa tất cả biến từ các file trên

Lưu ý

File .env.local và .env.*.local nên được thêm vào .gitignore. Chúng chứa secret riêng của từng developer/server.

`checkDBDialect()`

Kiểm tra và validate dialect database trước khi khởi động:

typescript

checkDBDialect();
// Throws nếu DB_DIALECT không hợp lệ
// Hỗ trợ: 'postgres', 'mysql', 'mariadb', 'sqlite'

`buildIndexHtml()`

Sinh file index.html cho client SPA, inject các biến cấu hình runtime:

typescript

await buildIndexHtml();
// Đọc template → inject API_BASE_URL, APP_NAME, etc. → ghi ra dist/

`genTsConfigPaths()`

Tự động sinh TypeScript path aliases cho workspace monorepo:

typescript

genTsConfigPaths();
// Scan packages/ → sinh tsconfig.paths.json
// Cho phép import '@digiforce-nc/server' thay vì đường dẫn tương đối

5) Environment setup

CLI đọc cấu hình từ environment variables. Các biến quan trọng:

Biến	Mô tả	Mặc định
`APP_PORT`	Cổng HTTP server	`13000`
`APP_HOST`	Host bind	`0.0.0.0`
`DB_DIALECT`	Loại database	`sqlite`
`DB_HOST`	Database host	`localhost`
`DB_PORT`	Database port	dialect-dependent
`DB_DATABASE`	Tên database	`digiforce`
`DB_USER`	Database user	-
`DB_PASSWORD`	Database password	-
`DB_STORAGE`	SQLite file path	`./storage/db/digiforce.sqlite`
`APP_KEY`	Secret key cho JWT/encryption	-
`PLUGIN_PACKAGE_PREFIX`	Prefix cho plugin package	`@digiforce-nc/plugin-`

Bắt buộc

APP_KEY phải được đặt trong production. Nếu thiếu, JWT token và encryption sẽ không an toàn.

6) Plugin generation helpers

CLI cung cấp tiện ích tạo scaffold cho plugin mới:

bash

# Tạo plugin mới với template
digiforce pm create my-plugin

# Cấu trúc sinh ra:
# packages/plugins/my-plugin/
# ├── src/
# │   ├── server/
# │   │   ├── plugin.ts        # Server plugin class
# │   │   └── index.ts
# │   └── client/
# │       ├── index.tsx         # Client plugin entry
# │       └── locale/           # i18n files
# ├── package.json
# └── tsconfig.json

Plugin scaffold bao gồm:

Server plugin class kế thừa Plugin với lifecycle hooks (afterAdd, beforeLoad, load, install)
Client entry đăng ký routes, components, settings pages
Locale files cho đa ngôn ngữ
package.json với đúng peerDependencies

7) Kiến trúc CLI

Mở rộng

CLI sử dụng commander.js bên dưới. Các plugin có thể đăng ký command riêng thông qua app.cli.command() - xem Server Application.

Mã nguồn

@digiforce-nc/cli ​

1) Tổng quan ​

2) Bảng lệnh chính ​

Lifecycle commands ​

Plugin management (pm) ​

Schema export / import (schema) ​

3) Flow xử lý lệnh ​

4) Utility functions ​

initEnv() ​

checkDBDialect() ​

buildIndexHtml() ​

genTsConfigPaths() ​

5) Environment setup ​

6) Plugin generation helpers ​

7) Kiến trúc CLI ​

@digiforce-nc/cli

1) Tổng quan

2) Bảng lệnh chính

Lifecycle commands

Plugin management (`pm`)

Schema export / import (`schema`)

3) Flow xử lý lệnh

4) Utility functions

`initEnv()`

`checkDBDialect()`

`buildIndexHtml()`

`genTsConfigPaths()`

5) Environment setup

6) Plugin generation helpers

7) Kiến trúc CLI