Tasco Framework

Giao diện

Nợ kỹ thuật ​

Chỗ code core đang chưa đúng quy ước hoặc có lỗi đã biết mà chưa sửa. Danh sách nằm cuối CLAUDE.md và nhúng vào đây lúc build — cùng một nguồn cho dev đọc docs và AI đọc ngữ cảnh, để không ai lấy chỗ sai làm mẫu.

Danh sách hiện tại ​

  • useAiChat gọi toAppError({ statusCode }) nên mất status và message. useTable gọi void load() nên bị unhandled rejection khi fetch lỗi.
  • statusMessage tiếng Việt khiến h3 cảnh báo và toJSON() làm mất dấu. Giữ nguyên tới khi quyết định đổi sang message; nếu đổi thì sửa luôn TascoLoginForm.errorMessage().
  • Template CLI dùng (record as any).

Ghi nhận ​

  • Một dòng một vấn đề kiểm chứng được: tên hàm hoặc file, hệ quả cụ thể. "useTable gọi void load() nên lỗi lần tải đầu thành unhandled rejection" — không phải "useTable cần cải thiện".
  • Ghi ngay trong MR phát hiện ra, kể cả MR đang làm việc khác. Nợ lớn, cần bàn cách sửa thì mở thêm issue và dẫn link.
  • Người dùng framework có thể vấp phải thì ghi cả vào trang docs liên quan (mục Lưu ý hoặc Xử lý sự cố) kèm cách né.

Trả nợ ​

  1. MR sửa xoá dòng tương ứng trong CLAUDE.md và cập nhật ngày ở tiêu đề mục.
  2. Gỡ cách né đã ghi trong docs, nếu có.
  3. Kèm changeset khi đổi package; đổi hành vi người dùng nhìn thấy thì mô tả rõ trong changeset để lên Changelog.
  4. Sửa làm đổi API công khai thì theo phân tầng của RFC Process.

Rà soát ​

Trước mỗi version MR của bản minor, core team đọc lại danh sách: mục nào đã sửa mà quên xoá, mục nào cần nâng thành issue có người nhận.

Khác với gotcha ​

Gotcha là ràng buộc của công nghệ bên ngoài mà core đã chọn cách sống chung — không trả được bằng sửa code core. Chúng cũng nằm trong CLAUDE.md:

  • antd-vue bỏ qua theme.components trong ConfigProvider: style component-level phải làm bằng global CSS (base.css trong theme), KHÔNG cấu hình qua token components.
  • SSR với antd-vue kém → hybrid rendering: routeRules đặt ssr: false mặc định cho page, vẫn giữ Nitro BFF. Đừng bật SSR lại cho page dùng antdv nếu chưa test kỹ.
  • Đăng nhập IAM: form login qua endpoint IAM Tasco; userInfo gọi bằng POST không kèm Bearer; cookie chỉ giữ token (giới hạn 4KB) — không nhét thêm profile vào cookie.
  • Registry 404 với người ngoài team core: scope @tasco phải trỏ group endpoint (/api/v4/groups/tasco/-/packages/npm/), auth bằng Group Deploy Token scope read_package_registry. PAT cá nhân chỉ hoạt động khi user là member (≥ Reporter).
  • Chạy playground khi package chưa build (vd sau pnpm clean) → [TSCONFIG_ERROR] Failed to load tsconfig '../packages/nuxt-layer-base/.nuxt/tsconfig.json': layer chưa nuxi prepare, các package thiếu dist. Chạy dev qua turbo (task dev có ^build), đừng pnpm --filter playground dev; server đang lỗi phải restart (Vite cache lỗi tsconfig).

Gotcha hết hiệu lực (vd antdv bản mới đọc được theme.components) thì xoá khỏi CLAUDE.md và mở MR gỡ cách né trong code.

Liên quan ​