module.yaml — tham chiếu từng field

Schema đầy đủ, dùng chung giữa module-registry và lệnh validate của platform-cli (chưa triển khai): openapi/module-manifest.schema.json.

Bắt buộc

Field	Kiểu	Giải thích
code	string	Mã duy nhất toàn nền tảng. Chữ thường ASCII, số, gạch ngang; bắt đầu bằng chữ. Ví dụ hợp lệ: bao-cao, crm. Mã core dành riêng cho database lõi (ADR-0023) — không dùng được.
name	string	Tên hiển thị, tiếng Việt có dấu đầy đủ.
version	string	SemVer (1.4.0, 0.1.0-beta.1...). Bắt buộc tăng khi nộp phiên bản mới — nộp lại phiên bản không tăng bị từ chối với MODULE_VERSION_CONFLICT.
apiVersion	string	Phiên bản Platform API module tương thích, dạng v1.
sdkVersion	string	Khoảng tương thích SDK, ví dụ ">=1.2 <2.0". Một hoặc nhiều điều kiện (>=, >, <=, <, =) cách nhau bằng khoảng trắng, mọi điều kiện đều phải đạt. module-registry từ chối cài hoặc nâng cấp nếu phiên bản SDK của nền tảng nằm ngoài khoảng (ADR-0055).
vendor	string	Tên pháp lý của đối tác sở hữu module.
permissions	string[]	Toàn bộ quyền lớp 3 module yêu cầu, dạng {code}:{resource}:{action}, ví dụ bao-cao:tai-lieu:read. Danh sách này chỉ thêm, không xoá qua các lần phát hành (ADR-0046 mục 5) — khai đủ ngay từ bản đầu.

Tuỳ chọn

Field	Kiểu	Giải thích
description	string	Mô tả ngắn, tiếng Việt có dấu.
menus	object[]	Mục thực đơn giao diện, mỗi mục { path, label, permission }. Chỉ hiện khi người dùng có đúng permission đó.
routes	object[]	Tiền tố đường dẫn /api/v1/m/{code}/... và quyền tương ứng, mỗi mục { path, permission }. Gateway đối chiếu khi định tuyến.
migrations	string[]	Tên tệp migration chạy khi cài và nâng cấp, chuẩn Flyway: V{phiên bản}__{mô tả}.sql, ví dụ V1.0.0__khoi_tao.sql.
events	object	publish (sự kiện module phát, tiền tố đúng code), subscribe (sự kiện platform module muốn nhận), webhook (URL HTTPS nhận sự kiện ngoài môi trường chạy). Mỗi tên sự kiện dạng {code}.{entity}.{action}.
frontend	object	{ remote } — URL https:// điểm vào Module Federation, khớp remoteEntry.js.
resources	object	{ cpu, memory } — tài nguyên yêu cầu, platform áp bằng Kubernetes ResourceQuota theo gói tenant.
egress	object[]	Đích ngoài cụm module được gọi tới. Mọi kết nối ra Internet mặc định bị chặn — không khai nghĩa là module không ra Internet được (ADR-0066). Mỗi mục: host (FQDN hoặc IPv4, không ký tự đại diện), port, reason (tiếng Việt, 10–500 ký tự, nói rõ tính năng nào dùng và dữ liệu gì của tenant đi ra), credential (tuỳ chọn — tên biến môi trường platform tiêm bí mật từ Vault, không bao giờ là giá trị). Platform Admin duyệt egress cùng gói.
lifecycle	object	Móc chạy khi cài/nâng cấp/gỡ: { onInstall, onUpgrade, onUninstall }, mỗi giá trị là một chuỗi lệnh hoặc tham chiếu module tự định nghĩa cách đọc.
healthEndpoint	object	{ health, ready } — điểm kiểm sức khoẻ; platform dùng để quyết module ở trạng thái ACTIVE hay FAILED.

Ví dụ sdkVersion

sdkVersion: ">=0.1 <1.0"      # mọi bản 0.x, chưa sang 1.0
sdkVersion: "1.4.0"            # đúng bản này (không có toán tử nghĩa là khớp chính xác)
sdkVersion: ">=1.0 <2.0 !=1.5.0"   # không hợp lệ — "!=" không nằm trong tập toán tử cho phép

Ví dụ egress

egress:
  - host: api.vnpost.vn
    port: 443
    reason: Tra cứu mã vận đơn cho đơn hàng của tenant khi khách bấm "theo dõi đơn"
    credential: VNPOST_API_KEY

Ví dụ manifest tối giản hợp lệ

Xem gói demo đã dựng sẵn ở trang File mẫu — module.yaml trong đó là một ví dụ chạy được, qua được kiểm schema thật.