Giao diện
RFC 0003: Tái cấu trúc tài liệu framework
- Trạng thái: Accepted
- Người đề xuất: Core team
- Ngày: 2026-09-16
Bối cảnh & vấn đề
Docs hiện tại là VitePress với 15 trang (~1.800 dòng) cộng 2 RFC, tổ chức theo package. Quy trình đóng góp, release và Migration v1 → v2 đã đủ dùng; phần team sản phẩm cần hằng ngày thì thiếu, và có chỗ đang hướng dẫn sai.
Khảo sát ngày 15/09/2026 tại 08e7b14:
- Component: 17 component thương hiệu dồn trong một trang
guide/ui.md. 16 component chỉ có một dòng trong bảng, riêngCTablecó mục chi tiết. 50 primitive antdv re-export chỉ được liệt kê tên. Không có ví dụ chạy được, không có bảng props/events/slots đầy đủ. - Source chưa đủ để sinh tài liệu tự động: 7 component có prop nhưng không prop nào có JSDoc (
CAppLayout,CButton,CEmpty,CInputCurrency,CInputPercent,CPageHeader,CTopNav); không component nào khai báo slot bằngdefineSlots. - API chưa có tài liệu:
useConfirm,useErrorHandlervà$tascoError,useThemeMode,@tasco/utils(AppError,toAppError,getFieldErrors),error.vue, bảng biến môi trường đầy đủ. - Sai lệch (sửa riêng ở MR
fix/docs-sai-lech, không chờ RFC này):.npmrchướng dẫn trỏ instance endpoint/api/v4/packages/npm/ởguide/getting-started.md,contributing/npmrc.mdvà template CLI, trong khiCLAUDE.mdvàguide/ai-tooling.mdnói đúng phải là group endpoint — đây là nguyên nhân lỗi E404 khi cài package.- Permission dạng
order.readcòn ở docs, template CLI, mock đăng nhập, playground và comment middleware; thực tế permission là URI so khớp chính xác. - Ví dụ trong
guide/ui.mdviết thẻ<a-dropdown>,<a-menu>,<a-form-item>, trái quy tắc app chỉ dùngC*. README.mdcòn ghi dòng 1.2.x/1.3.x; sơ đồguide/architecture.mdthiếuai,mcpvà quan hệcomposables → theme.
- Phiên bản: site chỉ có một bản, tự deploy từ
main, nên tài liệu luôn là của major mới nhất — team đang ở major cũ không có bản tương ứng để đọc. Remote cũng chưa có tag phát hành vì jobreleasekhông đẩy tag. - Trải nghiệm: chưa bật tìm kiếm, chưa có "Sửa trang này", chưa hiện ngày cập nhật. Trang dài khiến
search_docscủa@tasco/mcptrả cả file thay vì đúng đoạn.
Đề xuất
1. Chia theo người đọc: 6 khu, khoảng 98 trang
Tên package chỉ còn là nhãn trong khu Tra cứu. Mỗi trang một việc, theo khung Diátaxis (Học / Làm / Hiểu / Tra cứu).
| Khu | Đường dẫn | Người đọc | Số trang |
|---|---|---|---|
| Bắt đầu | /v2/start/ | Team sản phẩm | 5 |
| Hướng dẫn | /v2/guide/ | Team sản phẩm | 27 |
| Component | /v2/components/ | Team sản phẩm | 33 |
| UI/UX | /v2/design/ | Designer, BA, dev | 8 |
| Tra cứu | /v2/reference/ | Mọi người | 10 |
| Phát triển core | /v2/core/ | Team core | 15 |
- Bắt đầu: giới thiệu, chuẩn bị môi trường và registry, tạo app bằng CLI, hướng dẫn làm từng bước một app quản lý đơn hàng, thêm vào project có sẵn.
- Hướng dẫn: nền tảng (layer, cấu hình, chế độ render), gọi backend (BFF, hợp đồng dữ liệu, fetcher), đăng nhập và phân quyền (7 trang tách từ
auth.md), xử lý lỗi, 4 mẫu trang (danh sách, form, chi tiết, dashboard), giao diện, AI, vận hành (deploy, nâng cấp, xử lý sự cố). - Component: mỗi component một trang;
CTabletách 6 trang con; 6 trang cho primitive antdv re-export theo nhóm;TascoLoginForm,Can/v-can,useConfirm,useErrorHandler. - Phát triển core: 4 trang contributing hiện có chuyển sang, cộng kiến trúc nội bộ, thêm component/composable, test và coverage, đổi design token, viết tài liệu, CI/CD, MCP và AI review, nợ kỹ thuật.
URL cũ chuyển hướng bằng _redirects của Cloudflare Pages, giữ ít nhất tới hết major 2.
2. Chuẩn trang component
Mọi trang theo cùng thứ tự: mở đầu (khi nào dùng / không dùng) → ví dụ cho từng trường hợp → API sinh từ source → giao diện và biến CSS → khả năng tiếp cận → lưu ý → liên quan.
Trang xong khi: mọi prop/event/slot có mô tả (bảng API không còn ô cảnh báo); có demo cơ bản, demo cho mỗi biến thể chính, mỗi trạng thái component có, và ít nhất một ví dụ ghép thực tế (useTable, CForm, phân quyền); demo chỉ dùng C* và composable công khai, qua vue-tsc và ESLint với cấu hình của template CLI; một người không viết trang làm theo được.
3. Docs-as-code
- Ví dụ là code thật: mỗi ví dụ dài hơn 10 dòng là file
.vuetrongdemos/của trang, render bằng cú pháp<demo src>trong<ClientOnly>(antdv render phía server kém — gotcha đã biết), code hiển thị đọc từ chính file đó. - Bảng API sinh từ source:
vue-component-meta(cùng engine với vue-tsc 2.2) chạy trong build@tasco/ui, xuấtcomponent-meta.jsonvàodist. VitePress và@tasco/mcpdùng chung file này;@tasco/mcpbỏ parser regex hiện tại (không đọc được slot và payload event). - Tra cứu package TS: TypeDoc +
typedoc-plugin-markdownchocomposables,utils,theme,ai. - Token: bảng màu và tỉ lệ tương phản sinh từ
cssVars()vàcontrast.tscủa@tasco/theme. - CI: job
docschặn khi build gặp link hỏng, demo lỗi vue-tsc hoặc ESLint, hoặcdocs-coveragethấy exportC*, prop, event, slot, khoá runtimeConfig chưa có tài liệu. Cảnh báo từ M1, chặn MR từ M3. - Quy ước code nhúng từ
CLAUDE.mdbằng<!--@include-->, không chép tay.
4. Docs theo phiên bản, bắt đầu từ 2.x
Đơn vị là major (các package đi lockstep; trong một major, minor chỉ thêm tính năng tương thích ngược). Không dựng tài liệu cho 1.x: team còn ở 1.x nâng lên theo Migration v1 → v2 nằm trong bản 2.x.
| Đường dẫn | Build từ | Nội dung |
|---|---|---|
/v2/ | main | Cấu trúc mới; demo chạy @tasco/ui 2.x. / chuyển hướng về đây |
/v3/ (khi 3.0 ra mắt) | main | Bản 2.x lúc đó chuyển sang nhánh release/2.x và vẫn phục vụ ở /v2/ |
- Đường dẫn cố định theo major: app 2.x (template CLI,
CLAUDE.mdcủa sản phẩm, MCP) trỏ/v2/…và vẫn đúng sau khi 3.0 ra mắt. - Mỗi bản build từ nhánh của nó nên demo luôn khớp phiên bản. Storybook không chia phiên bản.
- Menu phiên bản và banner bản cũ đọc
/versions.jsonở gốc site lúc chạy, nên bản cũ không phải build lại khi có bản mới. - Trong một major: JSDoc
@sincehiện badge "từ 2.1"; phần đã merge nhưng chưa phát hành hiện "sắp phát hành" (so@sincevới version trongpackage.json).docs-coveragesocomponent-meta.jsonvới bản@tasco/uiđã publish để bắt prop/event/slot mới thiếu@since. - Hiện site chỉ có một bản nên job deploy giữ như cũ, chỉ thêm
base/v2/và_redirects. Từ bản cũ đầu tiên (khi 3.0 ra mắt): Cloudflare Pages thay toàn bộ site mỗi lần deploy, nên job deploy trênmainbuild bản mới rồi tải artifact của nhánhrelease/<major cũ>.xqua API artifact của GitLab và ghép lại; không tải được thì job dừng, không deploy site thiếu phiên bản. Push vào nhánh duy trì thì build artifact rồi kích hoạt pipelinemain. - Checklist phát hành major mới nằm ở trang Release của khu Phát triển core.
5. Quy trình và quyền sở hữu
- MR đổi API công khai chỉ xong khi có JSDoc, trang docs, demo, changeset và Migration nếu breaking.
docs-coveragekiểm tự động. CODEOWNERStrỏ theo thư mục docs mới (docs/components/**cho owner UI,docs/guide/auth/**cho owner platform…).- MR template thêm mục docs và ảnh chụp cho MR đổi giao diện; skill
new-componentthêm bước viết trang và demo; thêm skilldoc-componentsoạn nháp trang từ source. - Không có preview theo MR: người review chạy
pnpm turbo run dev --filter=docs. - Site giữ công khai. Quy tắc nội dung: không đưa token, secret; host IAM và gateway trong ví dụ dùng
example.com; chỉ ghi host thật khi người đọc bắt buộc phải cấu hình đúng host đó (registry GitLab).
6. Lộ trình
12 tuần, khoảng 107 ngày công trên năng lực khoảng 120 (2 dev core toàn thời gian). Designer tham gia khoảng 30% ở tuần 7–10; 1 dev team sản phẩm dùng thử khoảng 3 ngày; core lead duyệt RFC và MR.
| Giai đoạn | Tuần | Ngày công | Kết quả |
|---|---|---|---|
| GĐ0 Chốt phạm vi, chuẩn viết, sửa sai lệch | 1 | ~5 | RFC duyệt, hướng dẫn viết + template |
| GĐ1 Hạ tầng docs (theme, demo, API, phiên bản, CI) | 2–3 | ~14 | M1 09/10 — site mới tại /v2/ |
| GĐ2 Bắt đầu và Hướng dẫn | 3–6 | ~25 | M2 30/10 — team sản phẩm tự onboarding |
| GĐ3 Component, 3 đợt | 4–9 | ~30 | M3 20/11 — đủ trang, docs-coverage chặn MR |
| GĐ4 UI/UX, Tra cứu, Phát triển core | 7–10 | ~26 | 33 trang còn lại |
| GĐ5 Đồng bộ MCP, quy trình, ra mắt | 10–12 | ~7 | M4 11/12 — công bố chính thức |
Thiếu người thì lùi GĐ4 trước, giữ GĐ2 và GĐ3 để mốc M2 không trượt.
Phương án thay thế
| Nhu cầu | Chọn | Không chọn vì |
|---|---|---|
| Ví dụ chạy được | Plugin demo trong VitePress, file .vue vừa chạy vừa là code hiển thị | Nhúng iframe Storybook: nặng, lệch theme, code không đồng bộ. Code viết trong markdown: không typecheck, dễ lệch |
| Bảng API | vue-component-meta | Parser regex hiện tại của MCP không đọc được slot và payload event; viết tay thì lệch source |
| Tìm kiếm | Local search của VitePress, chuẩn hoá bỏ dấu tiếng Việt | Algolia DocSearch phải gửi nội dung nội bộ ra dịch vụ ngoài |
| Phiên bản | Mỗi major một bản, build từ nhánh của major đó | Chép thư mục docs cho từng bản trong cùng nhánh: demo sẽ chạy @tasco/ui mới nhất, sai với bản cũ |
| Tổ chức | Theo người đọc | Theo package: người đọc phải biết trước API nằm ở package nào mới tra được |
Ảnh hưởng
- Không breaking với API runtime. Package thay đổi:
@tasco/ui(patch): JSDoc cho mọi prop/emit,defineSlotscho 17 component, sinhcomponent-meta.jsonvàodist. Cần chạy vue-tsc với playground và app tạo từ CLI trước khi phát hành vìdefineSlotscó thể làm lộ lỗi type sẵn có ở app sản phẩm.@tasco/mcp(minor): đọccomponent-meta.json, chia docs theo heading, trả link/v<major>/. Giữ coverage 90%.@tasco/cli(patch): link docs trong template trỏ/v2/.
- URL đổi: mọi link docs hiện có. Giảm thiểu bằng
_redirectsvà cập nhật template CLI trong cùng đợt. - CI: thêm job
docs; job deploy chỉ thêmbase/v2/và_redirects, phần ghép nhiều phiên bản để tới khi có bản cũ đầu tiên (3.0). - Team sản phẩm: không phải làm gì; link cũ vẫn vào được. Team còn ở 1.x không có tài liệu riêng — nâng lên 2.x theo Migration v1 → v2.
Quyết định đã chốt (15/09/2026)
| # | Câu hỏi | Chốt |
|---|---|---|
| 1 | Site docs đặt sau đăng nhập? | Chưa cần ở thời điểm hiện tại; áp quy tắc nội dung cho site công khai |
| 2 | Vai trò Storybook? | Chưa thể hiện được vai trò → không đầu tư thêm, giữ nguyên bản build ở /storybook/, trang component không link story, đánh giá lại ở GĐ5 |
| 3 | Duy trì docs theo phiên bản? | Có, tính từ 2.x trở đi; không dựng tài liệu cho 1.x (chốt 16/09/2026) |
| 4 | Nhân sự | 2 dev core, designer ~30% tuần 7–10, 1 dev team sản phẩm ~3 ngày, core lead duyệt |
| 5 | Preview docs theo MR? | Không |
| 6 | Demo cần primitive antdv chưa re-export | Thêm alias vào @tasco/ui, demo không viết thẻ <a-*> |
| 7 | Storybook sau GĐ5 (đánh giá lại câu 2) | Chỉ giữ làm công cụ dev cục bộ (HMR trên source, panel a11y): không deploy, /storybook/* chuyển hướng về trang Component; .stories.ts tuỳ chọn, trang docs + demo bắt buộc (chốt 16/09/2026) |
Câu hỏi mở
@sincetự động (mục 4) chưa làm: bảng API chưa hiện badge,docs-coveragechưa so với bản đã publish. Tạm thời mục docs mô tả API mới gắn nhãn taytừ x.y(Viết tài liệu › API mới trong một major). Cần chốt nguồn để so: registry (pipeline MR phải có token đọc) hay bảncomponent-meta.jsonlưu lại trong version MR.- Có bổ sung đẩy tag phát hành trong job
releasekhông, để khi tạo nhánh duy trì cho major cũ (lần đầu là lúc 3.0 ra mắt) lấy mốc bằng tag thay vì tra lịch sửpackage.json. - Thời điểm xem lại chính sách truy cập site, khi các trang hạ tầng và bảo mật chi tiết hơn.