Giao diện
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:authorizegiờ bắt buộc. Trước đây bỏ trống là không kiểm tra gì, mà middlewareauth.globalcủa layer chỉ chạy ở client nên không bảo vệ route server: ai cũng gọi được/api/ai/chatvà tiêu key gateway. Thiếuauthorizethì handler ném lỗi ngay khi tạo.Cách sửa ở app (
server/api/ai/chat.post.ts): thêmauthorize: (event) => getTascoSession(event) != null(getTascoSessionauto-import từ layer). Endpoint công khai có chủ đích thì truyền() => true.Kèm theo:
- Option mới
maxTokens(mặc định4096):max_tokensclient 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.
- Option mới
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),Origintrù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ì khaiNUXT_CSRF_ALLOWED_ORIGINS; tắt hẳn bằngNUXT_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 → 502Hệ 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_MOCKhoặcNUXT_SESSION_SECRETngắ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.
- Chống CSRF: middleware mới chặn request ghi (trừ
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),Gridvà typeTourStepProps.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-exportSlidercủa antdv, giữ nguyên API). Track và viền núm của slider dùng--tasco-color-primarythay 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ếpant-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-vuecủa@tasco-fe/uilà4.2.6(trước là^4.2.0, khớp với bản layer đã cài), templatecreate-tasco-appghimnuxt4.4.8(trước là^4.0.0) — đúng bản core đã test.composables —
useApi: hookonResponseError/onRequestErrorcủ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ềAppErrorvà 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àloadingcủ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/sessionkhô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à plugin02.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áexpiresAtthì trảuser: nullluô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ủaapiProxyTarget.v-cantự 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 CSPframe-ancestorstrongrouteRulescủ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ừ
UNLICENSEDsang 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, componentTasco*) giữ nguyên. - Cách nâng cấp và codemod: xem mục "v2 → v3" trong Migration.
- Đổi tên mọi package,
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)..npmrcchỉ cònauto-install-peers=true;Dockerfilebỏ BuildKit secretnpmrc;.gitlab-ci.ymlbỏ biếnNPM_TOKEN, bước ghi token và cờ--secret.--gitlab-hostgiờ chỉ điền vào.mcp.json(MCP server GitLab).- App đã scaffold từ bản 2.x: xoá dòng
@tasco:registryvà_authTokentrong.npmrc, bỏ--secretởdocker buildnế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-appthêm cờ--gitlab-host,--container-registry,--api-url(hoặc biến môi trườngTASCO_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.shcủ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 khiNUXT_AUTH_MOCK=truecó email@example.com. Không đổi hành vi runtime nào khác.
ai · composables · theme · utils —
@tasco-fe/themeexport danh sách cặp chữ/nền đã khoá tương phản; bổ sung TSDoc cho mọi export củatheme,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.
- Thêm
cli — -
@tasco-fe/cli: app scaffold chuyển CI từ.gitlab-ci.ymlsang Jenkins —Jenkinsfile.dev(nhánhdev: check → build image bằng kaniko → deploy máy dev qua SSH) vàJenkinsfile(nhánhmain: 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_componentcó đủ 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/uivà link trang nhóm primitive, thay vì "Không tìm thấy".list_componentsliệt kê thêm primitive antdv re-export qua@tasco-fe/ui.search_docstrả từng mục##/###kèm linkhttps://web.docs.vtii.vn/v2/…#anchorvà đ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
instructionslúc kết nối: tool nào dùng cho việc gì, app không important-design-vue. - Kiểu export
ComponentMetacó thêmevents,slots,docsUrl;DocEntrycó thêmurl,level;Knowledgecó thêmprimitives. Trường cũ (emits,props[].optional) giữ nguyên.
theme · ui —
@tasco-fe/themeexportluminanceOfvàcontrastRatioOf; meta của@tasco-fe/uighi 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 —
CFormexpose API của form qua template ref:validate,validateFields,resetFields,clearValidate,scrollToField.- Trước đây
CFormkhôngdefineExposenênformRef.value.validate()làundefinedvà gọi sẽ némTypeError. Trang chỉ gửi form được bằng@finish+ núthtml-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 hayclearValidate()khi đổi giữa chế độ thêm/sửa. - Thêm kiểu public
CFormInstance(kèmCFormNamePath,CFormValidateOptions,CFormScrollOptions) để app khairef<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/uikhô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.
- Trước đây
ui — Bổ sung JSDoc cho mọi prop/event và
defineSlotscho component có slot; build sinh thêmdist/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áodefineSlotsđể slot vào được bảng API.CFormvàCTableforward slot động (tránh TS7022 của vue-tsc) nên chưa khaidefineSlots— slot#title,#toolbar,#filterFieldcủaCTablemô 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ằngvue-component-metalú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.
- Mỗi prop, event của 17 component
Sửa lỗi và cải tiến
cli — App scaffold ghim
@tasco-fe/mcptheo major (npx -y @tasco-fe/mcp@2) vàCLAUDE.mdcủa app hướng dẫn AI tra framework qua MCPtasco.- Trước đây
.mcp.jsongọi@tasco-fe/mcpkhô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ũ: đổiargscủa servertascothành["-y", "@tasco-fe/mcp@2"]. CLAUDE.mdthêm mục "Tra cứu framework":get_component,search_docs/read_doc,list_tokens.
- Trước đây
cli — README của
@tasco-fe/clibỏ lệnhpnpm create @tasco-fe/app(không có package@tasco-fe/create-appnên lệnh không chạy), hướng dẫnnpx @tasco-fe/cli <tên>hoặcpnpm 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-appnhắ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ửaDEPLOY_SERVERcùng các*_CREDENTIALS_IDtrongJenkinsfile.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ủaPOST /auth/login(NUXT_AUTH_MOCK=true) đổi permission từorder.read/order.writesang URI/orders/search,/orders/create,/orders/updatecho khớp IAM thật. Dự án đang dev bằng mock với permission dạngorder.readsẽ bị 403 — đổidefinePageMeta({ permissions }),can()vàv-cansang 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.mdvàCLAUDE.md. Sửa comment sai trongapp.config.tscủ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/mcpkhông còn host hạ tầng nội bộ (chuẩn bị publish công khai, RFC 0004).scripts/generate.tsthay host nội bộ (GitLab, API gateway) trong nội dung docs bằng<host-noi-bo>khi ghidata/*.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 sangexample.com.
nuxt-layer-base — Layer đặt
<html lang="vi">và khai kiểupermissiontrongRouteMeta.- 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.langtrongnuxt.config.ts. definePageMeta({ permission: '/orders/search' })đã được middlewarepermission.globalhỗ trợ nhưng chưa có trongRouteMetanên không có gợi ý kiểu. Không đổi hành vi.
- Trước đây thẻ
ui —
CInputPercentnhậ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,5theo thói quen thành125, 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
precisionkhi gõ và kẹp[min, max]khi rời ô như cũ. Ô hiển thị dấu phẩy, khớpCInputCurrency. - Tương thích ngược:
v-model:valuevẫ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.5sang12,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ữa125rồ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 theoprecision; trước đây lọt thành1.2345.
- Trước đây ô chỉ giữ chữ số và dấu chấm: người dùng gõ
ui —
CInputPercentgõ được số âm khiminâm; sửa hướng dẫn đặt dấu%trong docs.- Trước đây ô bỏ dấu
-khi gõ, nênminâm (vd-100cho tỉ lệ tăng trưởng) chỉ có tác dụng với value truyền từ ngoài. Naymin < 0thì giữ một dấu-ở đầu số (gõ-12,5→'-12.5').mintừ0trở lên (mặc định) vẫn bỏ dấu-như cũ. - Ô có
minâm dùnginputmode="text"vì bàn phím số (decimal) của iOS không có phím-; ô khác giữinputmode="decimal". Truyềninputmodevẫ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 raNaN. - Docs: ô vốn có sẵn hậu tố
%, nhưng trang component lại khuyên đặt%ở nhãn hoặcaddon-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ạnhCInputPercentthì bỏ đi; cần đơn vị khác (vd%/năm) thì truyềnsuffix.
- Trước đây ô bỏ dấu