Giao diện
Handbook
Tài liệu trong repo này bổ sung cho mã trong packages/, tập trung kiến trúc, core và plugin - không thay thế hoàn toàn site docs chính thức.
Cấu trúc nội dung
1. Kiến trúc tổng thể
| Tài liệu | Nội dung |
|---|---|
| Kiến trúc | Mục lục và thứ tự đọc phần kiến trúc |
| Tổng quan hệ thống | Context, boundary, nguyên tắc thiết kế, deployment |
| Server architecture | Koa app, hai tầng middleware, ResourceManager, DataSource |
| Client architecture | React SPA, managers, provider chain, rendering |
| Data model & metadata | Collection, Field, UI Schema, metadata-driven workflow |
| Plugin architecture | PluginManager, lifecycle, extension points, dependency |
| Security model | AuthManager, ACL Engine, pipeline bảo mật |
| Request lifecycle | End-to-end flows, install/upgrade, debug checklist |
2. Core (packages/core) - ưu tiên đọc trước plugin
| Tài liệu | Nội dung |
|---|---|
| Core - mục lục & thứ tự đọc | Hub, lộ trình 01 -> 09 |
| Bản đồ gói | Package → vai trò, trục debug |
| Luồng request & dữ liệu | Resource → ACL → repository |
| Server - Application | Koa app, sự kiện vòng đời, PluginManager server |
| Client - Application | SPA, PluginManager client, schema, APIClient |
| Database: Collection & Repository | Collection, repository, hook |
| Resourcer & Actions | Resource, action, Context |
| DataSourceManager | Nhiều data source (server); lưu ý khác client |
| Engine ACL | @digiforce-nc/acl: role, allow, snippet, middleware |
| Auth & AuthManager | @digiforce-nc/auth, JWT, kiểm tra public |
3. Plugin
| Tài liệu | Nội dung |
|---|---|
| Tài liệu plugin (developer) | Quy ước thư mục, template, danh sách |
Ai đọc phần nào
- Kiến trúc sư / tech lead:
architecture/, sau đócore/. - Developer plugin / tích hợp: đọc
core/01–09(tối thiểu02,03,06,08), sau đóarchitecture/05-plugin-architecture.md,plugins/README.md, rồi từngplugin-*. - Vận hành: ưu tiên từng plugin có
04-ui-user-guide.mdvà06-troubleshooting.md.
Nguyên tắc cập nhật
- Mô tả phải khớp với code trong
packages/corevàpackages/pluginstại nhánh hiện tại; khi refactor lớn, cập nhật lại handbook. - Chi tiết API từng module: ưu tiên README/
index.mdtrong package + bài deep-dive trongcore/khi đủ thời gian.