Quản trị dự án cho đội ngũ React

lattice governance assess kết luận mức tuân thủ của các app Next.js, Vite + React và React theo tám miền xác định trong phiên bản 0.5.0: danh sách app, policy dependency trực tiếp, kiến trúc source, bảo mật dependency, chất lượng mã, bảo mật mã, tương thích trình duyệt/mobile và khả năng tiếp cận. Kết quả đạt chỉ áp dụng cho các rule đã cấu hình, không chứng nhận mọi kiểm soát của doanh nghiệp.

Cài @anhcodo13/lattice@0.5.0 với Node.js 24+ để chạy bản đánh giá tám miền. Bản 0.4.0 có bảy miền; 0.5.0 bổ sung ngưỡng thư viện có điều kiện và bằng chứng accessibility.

Miền	Bằng chứng	Ngưỡng mặc định
Danh sách app	Đúng tập đường dẫn/profile	Mọi app phát hiện được đều khai báo
Policy dependency	Range manifest, import source, importer npm/pnpm và phiên bản khóa	Framework bắt buộc và thư viện đang dùng đạt ngưỡng đã duyệt
Kiến trúc	Đồ thị import nội bộ, ranh giới và điểm	Điểm ≥75, không có finding error hoặc vòng module-cycle
Bảo mật dependency	npm/pnpm audit trên lockfile	Không có advisory high hoặc critical
Chất lượng mã	ESLint, TypeScript, Vitest và độ phủ dòng V8	Không có lỗi lint; typecheck đạt; test đạt; coverage ≥70%
Bảo mật mã	Semgrep p/ci và Gitleaks	Không có finding SAST high/critical hoặc secret
Tương thích	Playwright trên trình duyệt và thiết bị mô phỏng	Chromium, Firefox, WebKit, Android Chrome, iPhone Safari mô phỏng; hai viewport và phiên bản engine cho mỗi project
Khả năng tiếp cận	Kết quả axe trên trang Playwright đã render	Quét Chromium desktop và Android Chrome theo tag WCAG 2.1 A/AA; không có vi phạm hoặc mục chưa kết luận

1. Commit danh sách app chính xác

Đặt .nklattice-apps.json tại thư mục truyền cho governance assess:

{
  "schemaVersion": 1,
  "apps": [
    { "path": "apps/next", "profile": "next" },
    { "path": "apps/vite", "profile": "vite-react" },
    { "path": "apps/react", "profile": "react" }
  ]
}

App độc lập dùng "path": ".". Đường dẫn tính từ gốc quét, không trùng và không trỏ ra ngoài. CLI tìm package.json, suy ra profile từ next, vite cùng react, hoặc react; cấu hình "nklattice": { "profile": "react" } trong manifest được ưu tiên. Tập đường dẫn/profile phải khớp chính xác với app được phát hiện. Thiếu app, thay app khác, thêm app chưa khai báo hoặc đổi profile sẽ cho incomplete. --expect-apps N kiểm thêm số lượng nhưng không thay inventory. Package không có profile hỗ trợ nằm ngoài tập quản trị; cần review inventory khi thêm package.

2. Duyệt policy trung tâm

governance/policy.json giữ schema 2 và dùng policy version 5.0.0. profiles đặt ngưỡng framework bắt buộc; managedPackages thêm ngưỡng cho thư viện được app khai báo hoặc import. Xem Thư viện React được quản trị. Ví dụ "react": ">=19.3.1" chấp nhận bản chính xác 19.3.1 hoặc ^19.3.1 vì mọi phiên bản được phép đều đạt ngưỡng. ^19.2.0 không đạt dù lockfile hiện khóa 19.3.1. CLI còn yêu cầu specifier trong lockfile npm/pnpm khớp khai báo và phiên bản khóa thỏa cả hai range. Ngưỡng không giới hạn trên có thể nhận major mới; đội app vẫn phải review tính tương thích.

assessment.architecture quy định minimumScore, maximumErrors, blockedRuleIds và các thresholds, weights, ranh giới import trong analysis. Mặc định yêu cầu điểm từ 75, không có finding mức error và không có module-cycle. ID bị chặn phải là rule tích hợp hoặc boundary trung tâm đang bật. .nklattice.json của app không thể hạ gate trong bản đánh giá. File đó vẫn dùng cho lệnh khám phá cục bộ lattice analyze.

{
  "assessment": {
    "architecture": {
      "minimumScore": 75,
      "maximumErrors": 0,
      "blockedRuleIds": ["module-cycle"],
      "analysis": {
        "thresholds": {},
        "weights": { "architecture": 40, "imports": 25, "components": 20, "complexity": 15 },
        "policies": [],
        "aliases": {}
      }
    }
  }
}

Review cả policy và inventory như thay đổi mã. policyVersion là nhãn phát hành; hash SHA-256 trong báo cáo xác định đúng nội dung đã dùng.

assessment.evidence còn yêu cầu advisory scan mới, không có advisory high/critical, không có lỗi ESLint, TypeScript đạt khi app có source TypeScript, có test chạy và không test lỗi, coverage dòng ≥70%, không có finding SAST high/critical hay secret. Ma trận Playwright gồm chromium-desktop, firefox-desktop, webkit-desktop, android-chrome, iphone-safari; mỗi project có ít nhất hai test ở hai chiều rộng viewport. minimumTestedBrowserVersions và minimumEmulatedOsVersions đặt ngưỡng môi trường kiểm thử đã duyệt; phiên bản đo được thấp hơn sẽ làm gate thất bại. Giá trị OS mobile lấy từ user agent mô phỏng, không phải OS chạy trên thiết bị thật; ngưỡng này cũng không chứng minh tương thích với bản cũ. Kết quả scanner thiếu, cũ hoặc sai định dạng là incomplete, không thể thành đạt.

3. Chạy và đọc kết quả

Workflow dùng lại cài dependency của app, Semgrep 1.136.0, Gitleaks 8.30.1 và browser engine Playwright. Lockfile của repo sử dụng cần có ESLint, TypeScript, Vitest với V8 coverage cùng test/cấu hình Playwright và @axe-core/playwright với phép quét có annotation trên Chromium desktop và Android Chrome. Xem Bằng chứng khả năng tiếp cận. Sau khi cài các công cụ trong repo sử dụng, thu evidence ngoài gốc quét trước khi đánh giá:

pnpm dlx @anhcodo13/lattice@0.5.0 governance run examples/governance \
  --policy governance/policy.json --expect-apps 3 \
  --evidence /tmp/nklattice-governance-evidence.json

Với app npm độc lập, dùng examples/standalone-react và --expect-apps 1. Khi quét một nhánh của workspace, --workspace-root cho phép dùng lockfile chung ở thư mục cha. --inventory chọn file inventory khác bên trong gốc quét. --output chọn thư mục báo cáo; mặc định là .nklattice-governance/. Lệnh tạo assessment.json và report.html tự chứa. Hai file thể hiện trạng thái từng miền theo app, finding, điểm, phiên bản scanner, coverage, ma trận tương thích, route và kết quả axe, hash policy/inventory/input, commit được quét và phạm vi chưa đánh giá. Workflow tải evidence chuẩn hóa và report lên artifact kể cả khi gate lỗi; không đưa giá trị secret thô vào artifact.

Mã	Ý nghĩa	Ví dụ
0	pass	Mọi miền bắt buộc có bằng chứng mới và đạt ngưỡng đã duyệt.
7	fail	Vi phạm đã đo, như advisory, secret, test lỗi hoặc browser test lỗi.
3	incomplete hoặc lỗi lệnh	Thiếu app, evidence cũ, scanner lỗi, bỏ sót source, thiếu browser project hoặc policy sai.

Bộ quét kiến trúc đọc source JS/TS được hỗ trợ, gồm cả thư mục source ẩn trong mỗi app. Nó bỏ qua node_modules, .git, .next, dist, build, out, coverage, thư mục công cụ sinh ra và .d.ts. Bộ quét theo import tĩnh, import() với đường dẫn cố định và require() với đường dẫn cố định. Import động không có đường dẫn cố định, source sai cú pháp hoặc import nội bộ không phân giải khiến kết quả chưa đủ bằng chứng. CSS/JSON và asset không phải code có thể được import nếu file tồn tại, nhưng không thành node trong đồ thị. Alias Vite phải khớp analysis.aliases trung tâm đã kiểm tra hoặc tsconfig.paths; target alias không thể xác minh sẽ cho kết quả incomplete. Việc phân giải package bên thứ ba nằm ngoài kiểm tra import nội bộ. Điểm là chỉ báo review, không cam kết app build/chạy đúng. Policy sai cú pháp dừng trước khi tạo báo cáo; log CI vẫn ghi lý do.

Chặn deploy tại repo sử dụng

Workflow dùng lại checkout SHA core-ref đầy đủ đã review, build CLI và lấy policy từ cùng commit. Sao chép ví dụ consumer, thay cả hai SHA bằng cùng commit, commit inventory và cho job deploy phụ thuộc governance. Repo gọi workflow phải giữ ref uses: bằng core-ref; workflow được gọi kiểm tra ref sau nhưng không tự chứng minh được hai ref bằng nhau. Đặt governance làm required merge check trong repo tiêu thụ.

Core đổi policy không tự chạy CI ở repo khác. Consumer cập nhật SHA đã pin và chạy lại gate. Ví dụ xanh trong repo NKLattice chỉ chứng minh ví dụ đó, chưa chứng minh mọi repo doanh nghiệp đã áp dụng.

Giới hạn của kết quả đạt

Bản đánh giá mới tra advisory dependency qua npm/pnpm audit, quét mã bằng Semgrep và Gitleaks, chạy test và browser project. Audit của pnpm workspace bao phủ lockfile chung; kết quả được gắn cho từng app như gate bảo thủ ở mức workspace, không khẳng định advisory thuộc riêng app đó. Dịch vụ advisory nhận thông tin package/version; bản thân NKLattice không tải source lên dịch vụ đó. Bộ rule Semgrep p/ci được duy trì từ xa nên nội dung có thể đổi giữa các lần chạy dù binary đã pin. Android/iPhone của Playwright là mô phỏng, không chứng minh app chạy trên một bản Android/iOS cụ thể của thiết bị thật. Ma trận xác minh engine và cấu hình mobile, còn giá trị của test do app viết vẫn phụ thuộc vào việc review test.

JSON bằng chứng là artifact đã chuẩn hóa, không phải chứng thực bằng mật mã. Timestamp, hash và commit giúp phát hiện đầu vào đổi ngoài ý muốn; người sửa được artifact hoặc kiểm soát CI runner vẫn có thể giả mạo kết quả cục bộ. Workflow dùng governance run để thu thập và đánh giá trong một tiến trình, không đọc lại artifact có thể chỉnh sửa. Chỉ coi kết quả đạt là bằng chứng chính thức trong workflow được bảo vệ trên runner tin cậy, với artifact báo cáo được bảo vệ. Giấy phép, hiệu năng runtime, quyền truy cập repo, branch protection và mức áp dụng giữa các repo vẫn ngoài phạm vi kết luận. Đây là baseline kỹ thuật, không phải chứng nhận theo TCVN 11930:2017 hay Thông tư 12/2022/TT-BTTTT. lattice governance check chỉ kiểm tra dependency vẫn dùng được với consumer schema 2 cũ.

Xem baseline quản trị web tại Việt Nam để đối chiếu từng phép kiểm, phạm vi accessibility và các công cụ đã đánh giá để tích hợp tiếp.