File này bàn giao branch fix/full-scan-review.

Cập nhật: 2026-08-11 (lần 4 — sau khi đảo nhóm output rename, xoá docx/document-builder, và bỏ toàn bộ re-export @sdcorejs/utils) · Base: main @ 25480b6.

git clone git@github.com:sdcorejs/sdcorejs-angular.git
cd sdcorejs-angular
git checkout fix/full-scan-review

# Orchestrator ở root (scripts sync/collect-docs/build-page)
npm install

# Workspace thư viện — v19 là NGUỒN SỰ THẬT, làm việc ở đây
cd versions/v19
npm install --legacy-peer-deps

Bắt buộc --legacy-peer-deps: lockfile của v20/v21 vẫn pin Angular 19 (sync bump package.json nhưng không regen lockfile). Đây là known issue có sẵn, ghi trong CLAUDE.md.

Môi trường đã dùng: Node v22.22.2, npm 10.9.7, Windows + PowerShell.

# từ versions/v19
npx ng lint
npm run build
npx ng test sdcorejs-angular --watch=false --browsers=ChromeHeadless

# từ root repo
npm run check:sync
npm run test:scripts
cd versions/v19 && npm run check:i18n-parity

Đọc theo thứ tự này; commit message của từng cái giải thích đầy đủ tại sao, không chỉ cái gì.

Người dùng đã chọn ba việc này khi bắt đầu. Ghi lại để không phải quyết lần nữa:

Một quyết định kỹ thuật quan trọng phát sinh trong lúc làm (nay là mặc định sau khi đảo nhóm output): (click) của <sd-button> giữ nguyên tên. Đổi thành sdClick sẽ khiến mọi (click) sẵn có của consumer âm thầm rơi về DOM event gốc — vẫn chạy, không lỗi biên dịch, nhưng payload khác và bỏ qua gate disabled. Đây là kiểu breaking im lặng, nguy hiểm nhất. Đã ghi trong CHANGELOG.md mục "Không đổi (có chủ đích)".

1. Review PR. 26 commit, ~1700 file. Đọc theo thứ tự commit; message của mỗi commit là phần giải thích chính.
2. Hỏi luật sư về vụ GPL — đã hết chặn: services/docx (code GPL) xoá hẳn khỏi source (2026-08-11, xem mục 4). Chỉ còn câu hỏi pháp lý KHÔNG chặn merge về các bản đã publish.
3. Thông báo breaking cho team dùng thư viện. Bảng migration đầy đủ nằm trong CHANGELOG.md, mục ### Changed (BREAKING for consumers).

Mỗi mục dưới đây đã được xác minh còn tồn tại tại thời điểm bàn giao.

Ba mục nợ trong bản bàn giao trước đã trả xong (2026-08-12):

• [hideInlineError] không có text node cho aria-describedby → message giờ render thêm vào span.sd-visually-hidden (class utility mới trong assets/scss), aria-describedby trỏ vào đó. Áp cho 12 control (input, input-number, textarea, select, autocomplete, date, date-range, datetime, chip, chip-calendar, time, editor). Có 2 spec guard ở sd-input. ⚠️ Bẫy khi sửa tiếp: @if chứa 2 root node thì Angular chiếu cả block vào slot mặc định, matSuffix mất tác dụng và cả icon lẫn span rơi khỏi suffix container — mỗi @if phải 1 root.
• aria-label mượn key i18n gần nhất → chỗ duy nhất còn ghi chú (sd-upload-file.md) thực tế đã có key riêng core.component.upload-file.remove; doc đã sửa lại cho đúng hiện trạng.
• Hai wrapper role="button" lồng phần tử tương tác → đã restructure: hàng menu sidebar-v1 chuyển role/tabindex/aria-current/(click)/Enter-Space xuống phần tiêu đề (nút ghim thành sibling độc lập); 3 card trên canvas form-builder bỏ hẳn role="button", affordance bàn phím/AT thành <button> thật đầu .fb-actions (aria-pressed + aria-label), toolbar hiện cả khi :focus-within.

Còn lại có chủ ý: 3 card form-builder giữ (click) cho chuột nên tắt 2 rule a11y tại đúng dòng (click-events-have-key-events, interactive-supports-focus) kèm comment giải thích — thêm tabindex/keydown vào card sẽ dựng lại chính cái bẫy vừa gỡ.

Đây là phần dễ mất thời gian nhất nếu không biết trước.

versions/v19/tsconfig.json map @sdcorejs/angular/* sang ./dist/sdcorejs-angular/* trước ./projects/sdcorejs-angular/*. Nghĩa là spec load thư viện đã build lần cuối cho mọi import chéo entry point — 59 spec + 215 file source. Sửa một file dùng chung mà không build lại thì spec của các file phụ thuộc không phản ánh thay đổi.

Đã sửa bằng cách override paths trong tsconfig.spec.json (trỏ về source). ng build vẫn resolve qua dist vì nó cần thế. Đừng revert.

spec.id gán theo thứ tự khai báo module, mà bundle esbuild không ổn định giữa các build. Cùng seed '5' cho hai thứ tự khác nhau. Seed giờ đọc từ env JASMINE_SEED và in ra đầu mỗi lần chạy — dùng nó để báo cáo lần chạy đỏ, nhưng đừng tin là replay được. Đã ghi comment 14 dòng trong karma.conf.js; đừng "sửa" nó thành "pin seed là đủ".

Ngôn ngữ (I18nService + localStorage) là state toàn cục. Jasmine random hoá thứ tự, nên một spec gọi setLanguage() mà không khôi phục sẽ làm spec khác đỏ tuỳ lần chạy — xanh khi chạy riêng, đỏ trong full suite. Đã gặp 3 lần. Cách xử lý: ghim ngôn ngữ trước khi render trong spec nào assert theo text, đừng tin giá trị mặc định.

Cùng lớp: window.IntersectionObserver bị stub mà không khôi phục cũng rò sang spec sau.

Get-Content sẽ hiển thị mojibake giả trên file tiếng Việt hoàn toàn sạch. Đã suýt "sửa" nhầm 2 lần. Muốn kiểm tra thật thì dùng:

[System.IO.File]::ReadAllText($path, [System.Text.Encoding]::UTF8)

Và quét mojibake theo codepoint (U+FFFD, U+00E2 U+20AC), không quét bằng mắt qua terminal.

Tương tự: .NET API ([System.IO.File]::...) dùng CWD của process, không phải Set-Location của PowerShell → luôn truyền đường dẫn tuyệt đối.

Hai agent cùng stash trong một worktree thì đè nhau. Đã xảy ra một lần (đã khôi phục, không mất gì). Muốn verify một spec là RED thì:

cp file.ts file.ts.bak
git show HEAD:path/to/file.ts > path/to/file.ts
# chạy spec
cp file.ts.bak file.ts && rm file.ts.bak

Đã thử khử trùng track key bằng hậu tố $index trong query-bar và hỏng: filter vừa bị xoá resolve ra key khác → toàn bộ chip bị huỷ và dựng lại. 3 spec bắt được. Ràng buộc đúng đắn (mảng filters không được chứa cùng một object hai lần, và object phải ổn định) giờ ghi trong sd-query-bar.md.

Không phải theo đường dẫn source. Đúng dạng là ./fesm2022/sdcorejs-angular-components-chart.mjs. ng-packagr copy nguyên field này sang dist/package.json.

Ghi lại từ CLAUDE.md vì đây là chỗ dễ sai nhất:

1. Chỉ sửa versions/v19/**. v20 và v21 là bản sinh ra. Sửa tay vào đó sẽ bị npm run sync ghi đè.
2. Sau khi sửa xong: npm run sync rồi npm run check:sync.
3. Doc đi cùng commit. Đổi public API mà không cập nhật sd-*.md tương ứng sẽ bị reject ở review. .md được coi là hợp đồng API, không phải phụ lục.
4. Mojibake là lỗi chặn. Quét trước khi commit bất kỳ thay đổi nào chạm văn bản không phải ASCII.
5. Comment // why: bằng tiếng Việt cho logic khó — giải thích tại sao, không phải cái gì.

CHANGELOG.md hiện có mục ## [Unreleased] đầy đủ. Bước 2 của release ritual là bắt buộc:

## [Unreleased]          →   ## [<release-suffix>] - YYYY-MM-DD
                             (và mở lại ## [Unreleased] rỗng ở trên)

Bỏ bước này thì published-docs/<version>/CHANGELOG.md của release đó sinh ra rỗng — collect-docs trích theo đúng heading ## [<suffix>].

Mỗi phase đi theo 3 bước:

1. Sửa — tự làm hoặc chia cho agent theo nhóm file không chồng nhau.
2. Cổng — ng build + ng lint + full suite. Không commit khi còn đỏ.
3. Review đối kháng — một agent độc lập đọc git diff với chỉ thị "tìm chỗ SAI, không khen, không đề xuất cosmetic".

Bước 3 là bước đáng giá nhất. Nó bắt 23 lỗi blocking mà 4600 test xanh không bắt được, trong đó có lỗi nằm trong chính fix vừa viết ra. Vài ví dụ:

• Fix connector thay control khi trùng tên, nhưng quên trả lại control cũ khi destroy → mất control gốc của consumer. Tệ hơn bug ban đầu.
• Một "tối ưu" cache trạng thái checkbox group tính từ cờ mà tại thời điểm đó chưa được đặt (CDK dựng header trước body) → checkbox khoá cứng sai. Pure pipe nên không bao giờ tự sửa.
• Một namespace mặc định cho storage nghe vô hại nhưng sẽ mồ côi toàn bộ dữ liệu đã lưu của consumer đang cấu hình đúng.

Nếu làm tiếp các đợt lớn, giữ bước 3.

Câu tóm tắt: phần lõi của thư viện tốt hơn hẳn phần release engineering của nó — check:sync, build và 4600 test đều xanh, và đó chính là lý do không ai thấy primary entry point export rỗng, 6 peer dep thiếu, cờ sideEffects khai sai, aria-hidden nằm trên 10 <input> thật, và CI chưa từng chạy test. Branch này sửa những cổng đó, và sửa luôn phần lớn thứ chúng lẽ ra phải bắt được.