Engineering Rules (Mandatory)

1. Scope

Áp dụng cho toàn bộ code trong v2/ và mọi task theo docs_hub_v3.

2. Architecture Rules

1. Monorepo boundary:
   • apps/api: runtime backend
   • apps/v2-portal: runtime frontend
   • libs/modules/*: domain modules
   • libs/core/*: shared technical core
2. Import nội bộ dùng alias @zalominiapp/* theo v2/tsconfig.base.json.
3. Không cho phép import chéo phá domain boundary (module A truy cập trực tiếp internals module B).

3. Security & Tenancy Rules

1. Auth/Tenant context theo DEC-001.
2. Zalo dual login theo DEC-002.
3. RBAC theo DEC-003:
   • Endpoint tenant-scope phải có @Permissions() và PermissionsGuard.
   • @Public() không đồng nghĩa bỏ TenantGuard.
   • @SkipTenantCheck() chỉ dùng cho auth/system-admin flow.
4. Không expose thông tin nhạy cảm trong response/log.

4. API & Data Contract Rules

1. DTO strict validate (whitelist, forbidNonWhitelisted, transform).
2. Datetime chuẩn ISO-8601 UTC theo DEC-004.
3. Id conventions:
   • FK lưu dưới dạng <field>Id hoặc <field>Ids.
   • Không embed object lớn trong document khi quan hệ có thể resolve bằng include.
4. Population strategy:
   • Mặc định không eager-load quan hệ.
   • Chỉ include theo whitelist query param.

5. Code Quality Rules

1. Mọi module mới phải có:
   • Unit tests cho service logic
   • Contract test cho API chính
2. Không merge khi:
   • Test đỏ ở phạm vi module thay đổi
   • Lint lỗi trong file thay đổi
   • Thiếu cập nhật docs traceability
3. Ưu tiên fix root-cause, không vá tạm workaround nếu chưa ghi debt rõ.

6. Documentation Synchronization Rules

Khi thay đổi code ở các nhóm dưới đây, bắt buộc cập nhật docs tương ứng:

Change Type	Bắt buộc cập nhật
Thêm/sửa endpoint	02_SPECS/core/backend_api.md, 03_TRACEABILITY/API_TRACEABILITY.md, 05_GENERATED/backend_api_manifest.md
Thêm/sửa schema/entity	02_SPECS/core/backend_api.md, 05_GENERATED/backend_entity_manifest.md
Thêm/sửa route UI	02_SPECS/core/portal.md, 05_GENERATED/ui_route_catalog.md, 03_TRACEABILITY/FEATURE_STATUS_MATRIX.md
Thêm/sửa quyền	00_GOVERNANCE/01_DECISION_LOG.md (nếu rule mới), 05_GENERATED/permission_manifest.md
Đổi logic kiến trúc	00_GOVERNANCE/01_DECISION_LOG.md + files spec liên quan

Manifest generation command (local/CI):

• cd v2 && npm run ci:manifest-guard

GitLab enforcement:

• CI job manifest_guard trong .gitlab-ci.yml phải pass trước merge MR.
• Branch protection settings theo 04_OPERATIONS/13_BRANCH_PROTECTION_POLICY.md.

7. Branch/PR Hygiene (Recommended)

1. 1 PR = 1 feature key hoặc 1 bug key.
2. PR description phải có:
   • Feature key
   • Files changed
   • Test evidence
   • Docs updated
3. Không gộp nhiều module unrelated vào cùng PR.