Tasco Framework

Giao diện

RFC 0002: Port thay đổi từ AntAdmin vào @tasco 2.0.0 ​

  • Trạng thái: Accepted
  • Người đề xuất: Core team
  • Ngày: 2026-09-14

Bối cảnh & vấn đề ​

AntAdmin (github.com/daothanh/antadmin, phát hành public trên npmjs) được tạo ngày 30/08/2026 từ working tree của repo này tại e14f2d4 cộng WIP scaffold CI/CD, bằng cách đổi tên cơ học tasco/Tasco/TASCO → antadmin/AntAdmin/ANTADMIN và thay domain nội bộ bằng domain public. Hai repo không chung lịch sử git.

Sau fork, AntAdmin có 44 commit (tới d07e34a, 14/09/2026). Trong đó có tính năng và bản sửa dùng chung mà @tasco/* chưa có:

  • CTable thành khung trang danh sách: toolbar, drawer bộ lọc, drawer thiết lập cột lưu localStorage, phân trang mặc định.
  • Token màu đạt tương phản WCAG AA, có test khoá cặp token; bật ESLint và Vitest cho @tasco/theme.
  • Sửa d.ts lỗi TS2749 của @tasco/ui và build Storybook.
  • Kiến trúc, coding conventions và quy trình trong CLAUDE.md.
  • Sửa app scaffold fail pnpm install/typecheck với pnpm 11+ khi đặt ngoài monorepo; gỡ phần OIDC còn sót trong layer.

Repo này sau fork chỉ thêm AGENTS.md và WIP ESLint 10, không sửa file tính năng nào, nên các commit trên áp được với xung đột nhỏ. Nếu không đồng bộ, hai codebase tiếp tục tách xa và mỗi bản sửa phải làm hai lần.

Đề xuất ​

  1. Port từng commit bằng scripts/port-antadmin.sh: map domain rồi đổi tên thương hiệu, bỏ pnpm-lock.yaml, CHANGELOG.md, LICENSE, .github/**; giữ tác giả, ngày và trailer Port-From: antadmin@<sha>; chặn commit khi còn nội dung public (npmjs, GitHub, domain AntAdmin).

  2. Giữ hạ tầng Tasco: scope @tasco, GitLab Package Registry, .gitlab-ci.yml, IAM Tasco mặc định, mock client OAP_*, template Docker dùng BuildKit secret, @tasco/mcp publish nội bộ.

  3. Không nâng toolchain trong đợt này: giữ pnpm 11.7.0, changesets 2, lock Nuxt 4.4.8 và engines.node của monorepo. pnpm 12, Nuxt 4.5, Vite 8, changesets 3 làm MR riêng sau 2.0.0.

  4. Phạm vi: port 22 commit, hoãn 2 (59eb902 nâng pnpm 12; 30aa5e9 đặt engines.node của monorepo theo Nuxt 4.5 trong khi lock còn Nuxt 4.4.8), bỏ 20 commit chỉ phục vụ bản public (phát hành npmjs và GitHub Actions, bỏ thương hiệu, version/CHANGELOG của npm, docs lên GitHub Pages). Danh sách đầy đủ ở .sync/antadmin.json.

  5. Chia MR xếp chồng, mỗi MR target nhánh ngay dưới, đổi target về main khi nhánh dưới đã merge:

    MRNhánhNội dung
    1feat/cli-scaffold-cicdChốt WIP scaffold CI/CD
    2feat/eslint-10Chốt WIP ESLint 10 (RFC 0001) + test cấu hình từ AntAdmin
    3docs/rfc-0002-port-antadminRFC này
    4feat/port-antadmin-toolingScript port, turbo dev phụ thuộc ^build, conventions trong CLAUDE.md, .gitignore, layer không publish file test, AGENTS.md
    5feat/port-antadmin-ui-kit11 commit theme + CTable, giữ thứ tự gốc
    6fix/port-antadmin-cli-layer6 commit CLI/layer ngày 14/09 + test template scaffold
    7docs/port-antadmin-migrationMigration Guide v1 → v2, sổ đồng bộ .sync/antadmin.json

  6. Phát hành chung @tasco/* 2.0.0 qua dist-tag beta, promote lên latest theo tiêu chí trong Release.

  7. Sau 2.0.0: AntAdmin làm upstream cho phần dùng chung, repo này là bản phân phối Tasco. Sau mỗi release AntAdmin, chạy script với dải <sha trong .sync/antadmin.json>..<sha mới>. Code dùng chung chỉ viết thương hiệu ở 3 dạng antadmin/AntAdmin/ANTADMIN và không hardcode domain, để việc đổi tên luôn cơ học.

Phương án thay thế ​

  • Chép đè snapshot AntAdmin rồi đổi tên một lần: nhanh nhưng mất lịch sử từng thay đổi và dễ kéo theo phần public hoá.
  • Team sản phẩm dùng thẳng @antadmin/* kèm layer Tasco mỏng: phải đổi --tasco-*, $tascoAuth, key tasco trong app.config.ts và cookie tasco_session (mọi người dùng bị đăng xuất), đồng thời phụ thuộc registry nằm ngoài GitLab công ty. Cần RFC riêng nếu muốn đi hướng này.
  • Không đồng bộ: hai codebase tách xa, sửa lỗi hai nơi.
  • Gộp nâng toolchain vào đợt port: khó khoanh vùng khi lỗi; bản thử đã đạt quality gate với toolchain hiện tại.

Ảnh hưởng ​

  • Breaking, phát hành major 2.0.0 cho mọi package @tasco/* (lockstep):

    • ESLint 10, Node >= 20.19 (RFC 0001).
    • CTable bọc trong khung CCard: class/style gắn vào khung ngoài; title và slot #title hiện ở header khung; phân trang mặc định có tổng số dòng và bộ chọn số dòng/trang.
    • Token màu đổi giá trị để đạt AA; ColorTokens thêm field bắt buộc accentText, successText, warningText.
    • useTable: bỏ sắp xếp thì sortField/sortOrder là undefined; dataIndex lồng gửi 'a.b'; sắp xếp nhiều cột lấy cột đầu.
    • Layer truyền locale vi_VN cho <a-config-provider>.
    • Layer gỡ OIDC: xoá server/utils/oidc.ts (các hàm auto-import getOidcMetadata, generatePkce, refreshAccessToken, mapUserInfo), runtimeConfig.oidc và env NUXT_OIDC_*, field refreshToken của session; /auth/logout không chuyển tới IdP.

  • Không breaking nhưng cần làm với app tạo từ template cũ: thêm pnpm-workspace.yaml có allowBuilds, field packageManager và dòng COPY trong Dockerfile; engines.node theo Nuxt 4.5.

  • Kiểm chứng với pnpm 11.7.0, Node 24:

    • feat/eslint-10, feat/port-antadmin-ui-kit, fix/port-antadmin-cli-layer và docs/port-antadmin-migration đều đạt pnpm install --frozen-lockfile, lint, typecheck, build (gồm docs) và test; nhánh cuối có 390 test.
    • Build Storybook đạt; playground /ui-kit kiểm tra tay CTable (drawer lọc, drawer thiết lập cột) ở theme sáng và tối.
    • App scaffold từ tarball, đặt ngoài monorepo: install, lint, typecheck, build đạt; tarball không còn workspace:*.
    • changeset version thử trên bản sao: mọi package @tasco/* lên 2.0.0.

  • Rà repo sản phẩm trước khi phát hành beta:

    bash
    grep -rnE '<CTable|NUXT_OIDC_|\.oidc\b|refreshToken|getOidcMetadata|generatePkce|refreshAccessToken|mapUserInfo|#ee0033|#1576f4|#4f76d1|#7b98df|#f43f5e|a-config-provider' \
  --include='*.vue' --include='*.ts' --include='*.css' --include='*.scss' --include='.env*' \
  --exclude-dir=node_modules --exclude-dir=.nuxt --exclude-dir=.output .

Câu hỏi mở ​

  • Chiều nguồn chuẩn sau 2.0.0: AntAdmin làm upstream (đề xuất) hay repo này làm upstream?
  • Repo sản phẩm nào dùng API bị đổi hoặc gỡ, và team nào pilot bản beta?
  • GitLab có bật push rule kiểm tra email tác giả không? Commit port đang giữ tác giả gốc.
  • Thời điểm nâng pnpm 12, Nuxt 4.5 và Vite 8 (kèm 30aa5e9).
  • Chưa chạy docker build --target check của template trên máy có Docker; playground/.env.example còn khối env NUXT_OIDC_* không còn tác dụng cần xoá.