Skip to content

Changelog ​

Thay đổi của các package @tasco-fe/* bản 3.x, gộp từ CHANGELOG.md của từng package. Các package phát hành cùng một số phiên bản (lockstep), nên mỗi phiên bản dưới đây áp cho cả bộ; thay đổi chạm nhiều package chỉ ghi một lần, kèm tên các package đó. Nâng cấp từ major trước: Nâng cấp phiên bản.

3.1.0 ​

Tính năng mới ​

  • ai · cli — Vá bảo mật createAiChatProxy: authorize giờ bắt buộc. Trước đây bỏ trống là không kiểm tra gì, mà middleware auth.global của layer chỉ chạy ở client nên không bảo vệ route server: ai cũng gọi được /api/ai/chat và tiêu key gateway. Thiếu authorize thì handler ném lỗi ngay khi tạo.

    Cách sửa ở app (server/api/ai/chat.post.ts): thêm authorize: (event) => getTascoSession(event) != null (getTascoSession auto-import từ layer). Endpoint công khai có chủ đích thì truyền () => true.

    Kèm theo:

    • Option mới maxTokens (mặc định 4096): max_tokens client xin vượt trần thì bị hạ về trần.
    • Client đóng tab hoặc bấm dừng thì request lên gateway bị huỷ theo, không để model sinh tiếp và tính tiền.
    • Gateway không trả header trong 10 giây hoặc không kết nối được → 502.
  • nuxt-layer-base — Siết bảo mật BFF:

    • Chống CSRF: middleware mới chặn request ghi (trừ GET/HEAD/OPTIONS) vào /api/** và /auth/** đến từ trang khác, trả 403. Request cùng origin (Sec-Fetch-Site: same-origin), Origin trùng host app (xét cả X-Forwarded-Host) và client không phải trình duyệt vẫn qua. App khác origin cần gọi BFF thì khai NUXT_CSRF_ALLOWED_ORIGINS; tắt hẳn bằng NUXT_CSRF_ENABLED=false.
    • Lỗi IAM không còn lộ ra client: IAM trả HTTP 401/403 → 401 Đăng nhập thất bại.; IAM 5xx, timeout, mất kết nối → 502 Hệ thống đăng nhập đang lỗi, thử lại sau. Trước đây status, body và URL nội bộ của IAM đi thẳng về trình duyệt.
    • Chặn cấu hình nguy hiểm ở production: bản build production bật NUXT_AUTH_MOCK hoặc NUXT_SESSION_SECRET ngắn hơn 32 ký tự thì route auth trả 500 nêu tên biến cần sửa. Kiểm tra env trước khi nâng cấp.
  • theme · ui — Bổ sung re-export các primitive antdv còn thiếu: nhập liệu (CAutoComplete, CCascader, CTreeSelect, CTransfer, CRate, CMentions, CSegmented), hiển thị (CList, CTimeline, CImage, CCalendar, CCarousel, CQRCode, CStatisticCountdown, CCheckableTag, CCardGrid, CCardMeta, CComment, CWatermark), phản hồi (CTour), điều hướng (CAnchor, CAffix, CBackTop, CFloatButton), Grid và type TourStepProps.

    Theme tối: Tag chọn được, FloatButton primary, Tour primary và mục đang xem của Anchor đạt tương phản 4.5:1; sửa số ngày đang chọn của Calendar toàn màn (chữ primary trên nền primary-active chỉ 1.78:1).

  • theme · ui — Thêm CSlider (re-export Slider của antdv, giữ nguyên API). Track và viền núm của slider dùng --tasco-color-primary thay cho tông nhạt mặc định của antdv để đạt tương phản 3:1 ở cả theme sáng và tối.

  • ui — Bổ sung re-export component con của các primitive antdv đã có (CInputPassword, CSelectOptGroup, CRadioButton, CUploadDragger, CWeekPicker/CMonthPicker/CQuarterPicker/CTimeRangePicker, CSubMenu/CMenuItemGroup/ CMenuDivider, CDropdownButton, CAvatarGroup, CBadgeRibbon, CSkeleton*, CDirectoryTree, CTableSummary*, CBreadcrumbSeparator, Compact) và các type antdv hay dùng (FormInstance, UploadFile, UploadChangeParam, UploadProps, TableColumnsType, TableColumnType, TablePaginationConfig, RadioChangeEvent, ModalFuncProps, MenuItemType) để app không phải import trực tiếp ant-design-vue.

Sửa lỗi và cải tiến ​

  • ai — @tasco-fe/utils@3.1.0

  • cli · ui — Khoá chặt version theo quy tắc của framework: peer ant-design-vue của @tasco-fe/ui là 4.2.6 (trước là ^4.2.0, khớp với bản layer đã cài), template create-tasco-app ghim nuxt 4.4.8 (trước là ^4.0.0) — đúng bản core đã test.

  • composables — useApi: hook onResponseError / onRequestError của caller (hàm hoặc mảng) không còn bị ghi đè âm thầm — chạy trước, rồi lỗi mới được chuẩn hoá về AppError và ném ra như cũ.

  • composables — useTable: đổi trang hoặc bộ lọc liên tục thì response về muộn của lần tải cũ không còn ghi đè dữ liệu, lỗi và loading của lần mới. Trước đây bảng có thể hiện dữ liệu lệch với trang hoặc bộ lọc đang chọn.

  • nuxt-layer-base — GET /auth/session không còn coi IAM sập là "chưa đăng nhập". Chỉ khi IAM từ chối token (401/403) mới trả user: null; IAM timeout, mất kết nối hay lỗi 5xx thì trả 502 kèm log server, và plugin 02.auth để lỗi hiện ra trang lỗi. Trước đây mọi người bị đá về trang login (đăng nhập cũng không được) và không có log nào. Token đã quá expiresAt thì trả user: null luôn, không gọi IAM.

  • nuxt-layer-base — - Proxy /api/**: backend không trả header trong 30 giây → 502 (trước đây treo vô hạn); body đã bắt đầu trả (tải file, stream) thì không bị cắt. Đường dẫn chứa .. sau khi giải mã hết (kể cả %2e%2e, %252e, %2f, Tomcat ..;) → 400, chặn thoát khỏi tiền tố của apiProxyTarget.

    • v-can tự cập nhật khi đăng nhập, đăng xuất hay nạp lại quyền; trước đây chỉ đổi khi component chứa nó render lại.
    • Header bảo mật mặc định cho mọi response: X-Frame-Options: SAMEORIGIN, X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin. App cần được nhúng iframe từ origin khác thì khai CSP frame-ancestors trong routeRules của dự án.

3.1.0-beta.0 ​

Sửa lỗi và cải tiến ​

  • ai — @tasco-fe/utils@3.1.0-beta.0

3.0.0 ​

Thay đổi phá vỡ tương thích ​

  • ai · cli · composables · eslint-config · mcp · nuxt-layer-base · theme · tsconfig · ui · utils — Đổi tên scope @tasco/* → @tasco-fe/* (breaking): scope @tasco đã có chủ trên npmjs, các package chuyển sang org @tasco-fe (RFC 0004).

    • Đổi tên mọi package, import, extends: ['@tasco-fe/nuxt-layer-base'], build.transpile, .mcp.json (@tasco-fe/mcp).
    • Giấy phép đổi từ UNLICENSED sang MIT (package công khai trên npmjs).
    • API, hành vi và giao diện không đổi. Tên trong chuỗi (tasco:<khu>:<tên>, --tasco-*, $tascoError, component Tasco*) giữ nguyên.
    • Cách nâng cấp và codemod: xem mục "v2 → v3" trong Migration.
  • cli — Template app scaffold không còn cấu hình registry GitLab và token (package @tasco-fe/* công khai trên npmjs).

    • .npmrc chỉ còn auto-install-peers=true; Dockerfile bỏ BuildKit secret npmrc; .gitlab-ci.yml bỏ biến NPM_TOKEN, bước ghi token và cờ --secret.
    • --gitlab-host giờ chỉ điền vào .mcp.json (MCP server GitLab).
    • App đã scaffold từ bản 2.x: xoá dòng @tasco:registry và _authToken trong .npmrc, bỏ --secret ở docker build nếu không dùng package riêng cần auth.

Tính năng mới ​

  • ai · cli · nuxt-layer-base — Template và tài liệu đi kèm package không còn ghi cứng host hạ tầng nội bộ (chuẩn bị publish công khai, RFC 0004).

    • create-tasco-app thêm cờ --gitlab-host, --container-registry, --api-url (hoặc biến môi trường TASCO_GITLAB_HOST, TASCO_CONTAINER_REGISTRY, TASCO_API_URL). Không truyền thì template dùng tên miền ví dụ (*.example.com) — team cần đặt biến một lần để scaffold ra đúng host của mình.
    • .npmrc, .gitlab-ci.yml, .mcp.json, docker-compose.*, .env.example, scripts/deploy-prod.sh của app mới dùng các giá trị trên.
    • @tasco-fe/nuxt-layer-base, @tasco-fe/ai: README và comment dùng host ví dụ; user mock khi NUXT_AUTH_MOCK=true có email @example.com. Không đổi hành vi runtime nào khác.
  • ai · composables · theme · utils — @tasco-fe/theme export danh sách cặp chữ/nền đã khoá tương phản; bổ sung TSDoc cho mọi export của theme, composables, utils, ai.

    • Thêm contrastPairs (cặp chữ/nền component đang dùng, kèm nơi dùng và ngoại lệ đã biết), pairContrastOf(pair, mode) (tương phản thấp nhất của cặp, nền gradient xét mọi điểm màu) và AA_TEXT_CONTRAST (4.5). Test khoá tương phản và bảng "Màu & tương phản" của docs cùng đọc danh sách này thay vì mỗi nơi giữ một bản.
    • Mọi export, thuộc tính interface và giá trị trả về của composable use* có TSDoc tiếng Việt — trang Tra cứu API sinh từ đây bằng TypeDoc, build docs báo lỗi khi export mới thiếu mô tả.
    • Chỉ thêm export và chú thích, không đổi hành vi runtime.
  • cli — - @tasco-fe/cli: app scaffold chuyển CI từ .gitlab-ci.yml sang Jenkins — Jenkinsfile.dev (nhánh dev: check → build image bằng kaniko → deploy máy dev qua SSH) và Jenkinsfile (nhánh main: check → build image). Registry image, máy dev và credential ID trong hai Jenkinsfile là giá trị ví dụ (__CONTAINER_REGISTRY__ lấy từ --container-registry, dev.example.com, registry-credentials.id, dev-server-ssh.id): đổi theo hạ tầng của team.

  • mcp — @tasco-fe/mcp đọc chung dữ liệu với site docs: component lấy từ @tasco-fe/ui/component-meta.json, docs tách theo mục và trả link đúng phiên bản /v2/ (RFC 0003).

    • get_component có đủ sự kiện kèm kiểu payload, slot (kèm props của slot) và link trang docs — trước đây parser regex chỉ đọc được props và tên sự kiện. Hỏi primitive antdv (CSelect, CInput…) nhận tên gốc antdv, cách import từ @tasco-fe/ui và link trang nhóm primitive, thay vì "Không tìm thấy".
    • list_components liệt kê thêm primitive antdv re-export qua @tasco-fe/ui.
    • search_docs trả từng mục ##/### kèm link https://web.docs.vtii.vn/v2/…#anchor và đoạn đầu nội dung, thay vì cả trang với đoạn trích 180 ký tự. Gõ không dấu vẫn khớp chữ có dấu; từ khoá ngắn (IAM, ui) khớp nguyên từ.
    • Tool mới read_doc: đọc đủ một mục (kèm mục con) hoặc cả trang theo link, route (/guide/auth/guard) hoặc đường dẫn file.
    • Nội dung docs của MCP có code demo, bảng API và token thật thay cho thẻ <demo>, <ApiTable>, <TokenTable>.
    • Server gửi instructions lúc kết nối: tool nào dùng cho việc gì, app không import ant-design-vue.
    • Kiểu export ComponentMeta có thêm events, slots, docsUrl; DocEntry có thêm url, level; Knowledge có thêm primitives. Trường cũ (emits, props[].optional) giữ nguyên.
  • theme · ui — @tasco-fe/theme export luminanceOf và contrastRatioOf; meta của @tasco-fe/ui ghi giá trị mặc định dễ đọc.

    • Hai hàm tính tương phản WCAG trước đây chỉ dùng nội bộ (test khoá cặp token) nay là API công khai — bảng token trong docs tính tỉ lệ tương phản bằng chính hàm này thay vì chép lại công thức.
    • component-meta.json: giá trị mặc định đổi từ literal JSON ("Xoá") sang dạng đọc được ('Xoá'); prop boolean không khai mặc định ghi rõ false đúng như Vue xử lý.
  • ui — CForm expose API của form qua template ref: validate, validateFields, resetFields, clearValidate, scrollToField.

    • Trước đây CForm không defineExpose nên formRef.value.validate() là undefined và gọi sẽ ném TypeError. Trang chỉ gửi form được bằng @finish + nút html-type="submit" — cách đó vẫn chạy, nhưng không làm được validate một phần (bước wizard), resetFields() sau khi lưu hay clearValidate() khi đổi giữa chế độ thêm/sửa.
    • Thêm kiểu public CFormInstance (kèm CFormNamePath, CFormValidateOptions, CFormScrollOptions) để app khai ref<CFormInstance>() mà không phải import từ ant-design-vue — ESLint chặn import đó, kể cả import type.
    • Chỉ mở đúng 5 hàm trên; hàm khác của antd Form (vd getFieldsValue) vẫn không expose để hợp đồng của @tasco-fe/ui không dính vào cây type của antd. Gọi API khi form chưa mount (hoặc đã bị gỡ) báo lỗi [@tasco-fe/ui] … thay vì TypeError.
    • Tương thích ngược: không đổi prop, slot hay sự kiện nào.
  • ui — Bổ sung JSDoc cho mọi prop/event và defineSlots cho component có slot; build sinh thêm dist/component-meta.json.

    • Mỗi prop, event của 17 component C* đều có mô tả tiếng Việt; component có slot khai báo defineSlots để slot vào được bảng API. CForm và CTable forward slot động (tránh TS7022 của vue-tsc) nên chưa khai defineSlots — slot #title, #toolbar, #filterField của CTable mô tả tay trong trang docs.
    • Thêm subpath @tasco-fe/ui/component-meta.json: props/events/slots kèm kiểu và mô tả, sinh bằng vue-component-meta lúc build. Docs (bảng API) và @tasco-fe/mcp (get_component) dùng chung file này thay vì mỗi nơi tự parse component (RFC 0003).
    • Chỉ thêm kiểu và dữ liệu, không đổi hành vi runtime.

Sửa lỗi và cải tiến ​

  • cli — App scaffold ghim @tasco-fe/mcp theo major (npx -y @tasco-fe/mcp@2) và CLAUDE.md của app hướng dẫn AI tra framework qua MCP tasco.

    • Trước đây .mcp.json gọi @tasco-fe/mcp không kèm version nên AI có thể đọc props và link docs của bản khác với bản app đang cài. App đã scaffold từ bản cũ: đổi args của server tasco thành ["-y", "@tasco-fe/mcp@2"].
    • CLAUDE.md thêm mục "Tra cứu framework": get_component, search_docs/read_doc, list_tokens.
  • cli — README của @tasco-fe/cli bỏ lệnh pnpm create @tasco-fe/app (không có package @tasco-fe/create-app nên lệnh không chạy), hướng dẫn npx @tasco-fe/cli <tên> hoặc pnpm dlx @tasco-fe/cli <tên> và liệt kê đủ file dự án sinh ra.

  • cli — Thông báo cuối của create-tasco-app nhắc đúng các file cần đổi host (Jenkinsfile*, docker-compose*.yml, .mcp.json, .env.example) thay vì .gitlab-ci.yml đã bỏ, và nhắc sửa DEPLOY_SERVER cùng các *_CREDENTIALS_ID trong Jenkinsfile.dev.

  • cli · nuxt-layer-base — Sửa mock đang hướng dẫn sai định dạng permission.

    • @tasco-fe/nuxt-layer-base: dữ liệu mock của POST /auth/login (NUXT_AUTH_MOCK=true) đổi permission từ order.read/order.write sang URI /orders/search, /orders/create, /orders/update cho khớp IAM thật. Dự án đang dev bằng mock với permission dạng order.read sẽ bị 403 — đổi definePageMeta({ permissions }), can() và v-can sang URI tương ứng.
  • cli · nuxt-layer-base — Template app trỏ tới các trang tài liệu mới của GĐ2 (hướng dẫn từng bước, mẫu trang, phân quyền, xử lý sự cố) trong README.md và CLAUDE.md. Sửa comment sai trong app.config.ts của layer: Nuxt nối mảng khi merge cấu hình giữa các layer (defu), không thay nguyên.

  • composables · nuxt-layer-base — Ví dụ trong comment, JSDoc và docs phân quyền dùng mã trung lập (ORDER_ADMIN, /orders/search) thay cho mã role và permission thật của một sản phẩm nội bộ. Không đổi hành vi.

  • mcp — Data đóng gói kèm @tasco-fe/mcp không còn host hạ tầng nội bộ (chuẩn bị publish công khai, RFC 0004).

    • scripts/generate.ts thay host nội bộ (GitLab, API gateway) trong nội dung docs bằng <host-noi-bo> khi ghi data/*.json. Link tới trang docs trong từng kết quả vẫn dẫn tới bản đầy đủ.
    • Email ví dụ trong docs (auth/config, auth/mock, bff-routes) đổi sang example.com.
  • nuxt-layer-base — Layer đặt <html lang="vi"> và khai kiểu permission trong RouteMeta.

    • Trước đây thẻ <html> không có lang: trình đọc màn hình đọc nội dung tiếng Việt bằng giọng mặc định của máy và trình duyệt gợi ý dịch trang. App cần ngôn ngữ khác thì ghi đè app.head.htmlAttrs.lang trong nuxt.config.ts.
    • definePageMeta({ permission: '/orders/search' }) đã được middleware permission.global hỗ trợ nhưng chưa có trong RouteMeta nên không có gợi ý kiểu. Không đổi hành vi.
  • ui — CInputPercent nhận dấu phẩy thập phân khi gõ và hiển thị theo quy ước Việt Nam (12,5).

    • Trước đây ô chỉ giữ chữ số và dấu chấm: người dùng gõ 12,5 theo thói quen thành 125, rời ô thì bị kẹp về max (mặc định 100) mà không có báo lỗi nào.
    • Nay dấu phẩy và dấu chấm đều là dấu thập phân (gõ nhiều dấu thì giữ dấu đầu tiên); vẫn cắt theo precision khi gõ và kẹp [min, max] khi rời ô như cũ. Ô hiển thị dấu phẩy, khớp CInputCurrency.
    • Tương thích ngược: v-model:value vẫn là chuỗi dấu chấm ('12.5'), code gọi API không phải đổi. Chỉ phần hiển thị trong ô đổi từ 12.5 sang 12,5 — test e2e đang kiểm giá trị hiển thị của ô thì cập nhật theo.
    • Khi ô phải sửa lại chuỗi vừa gõ (đổi . thành ,, bỏ ký tự lạ), con trỏ giữ đúng chỗ thay vì nhảy về cuối ô — chèn . vào giữa 125 rồi gõ tiếp vẫn ra đúng số.
    • Value truyền từ ngoài dùng dấu phẩy ('12,5') được chuẩn hoá về '12.5' khi rời ô, thay vì mất phần lẻ.
    • Dán chuỗi có nhiều dấu thập phân (vd 1.2.345) giờ cũng bị cắt theo precision; trước đây lọt thành 1.2345.
  • ui — CInputPercent gõ được số âm khi min âm; sửa hướng dẫn đặt dấu % trong docs.

    • Trước đây ô bỏ dấu - khi gõ, nên min âm (vd -100 cho tỉ lệ tăng trưởng) chỉ có tác dụng với value truyền từ ngoài. Nay min < 0 thì giữ một dấu - ở đầu số (gõ -12,5 → '-12.5'). min từ 0 trở lên (mặc định) vẫn bỏ dấu - như cũ.
    • Ô có min âm dùng inputmode="text" vì bàn phím số (decimal) của iOS không có phím -; ô khác giữ inputmode="decimal". Truyền inputmode vẫn ghi đè được.
    • Rời ô khi mới gõ dấu mà chưa có chữ số (-, ,) thì ô về rỗng (chưa nhập), thay vì để model '-' hay '.' mà Number() đọc ra NaN.
    • Docs: ô vốn có sẵn hậu tố %, nhưng trang component lại khuyên đặt % ở nhãn hoặc addon-after, làm % hiện hai lần. Đã sửa hướng dẫn và bỏ (%) khỏi nhãn trong demo, story, playground. App đang ghi (%) ở nhãn cạnh CInputPercent thì bỏ đi; cần đơn vị khác (vd %/năm) thì truyền suffix.