Kiến trúc

Mô hình phân phối

Core team sở hữu monorepo (pnpm + Turborepo), publish packages @tasco/* lên GitLab Package Registry ở cấp group tasco (xem Cấu hình .npmrc). Team sản phẩm không clone monorepo core — chỉ consume qua semver và extends Nuxt layer.

framework-core/ (core team)
└── packages/
    ├── nuxt-layer-base/   # entry point duy nhất team sản phẩm cần
    ├── ui/                # wrapper antdv
    ├── composables/       # useApi/useAuth/usePermission/useTable
    ├── theme/             # design token + ConfigProvider
    ├── utils/             # helper TS thuần
    ├── eslint-config/ tsconfig/   # convention
    ├── cli/               # create-tasco-app
    ├── ai/                # chat streaming + proxy AI gateway + prompts/eval
    └── mcp/               # MCP server tri thức framework cho AI tooling

Nuxt Layers

Framework đóng gói thành Nuxt Layer, không phải plugin rời. Team sản phẩm:

export default defineNuxtConfig({ extends: ['@tasco/nuxt-layer-base'] })

Layer share: app.config, components/composables auto-import, middleware, plugins, runtimeConfig defaults, Nitro server routes. Team override bằng cách định nghĩa lại file cùng đường dẫn (Nuxt ưu tiên layer gần nhất). Giữ tối đa 2 tầng layer (base → app).

Danh sách đầy đủ những gì layer mang theo và cách ghi đè từng phần: Layer cung cấp gì.

Quy tắc phụ thuộc

• nuxt-layer-base → ui, composables, theme, utils
• ui → theme, utils + ant-design-vue
• composables → theme, utils (không phụ thuộc ui)
• ai → utils; dùng tuỳ chọn ở app sản phẩm, không nằm trong layer
• mcp → không phụ thuộc package runtime; lúc build sinh dữ liệu từ ui (component-meta.json), theme và docs
• theme, utils: TS thuần, zero runtime dep

Luồng SSR + BFF

Browser ──/api/**──▶ Nitro (layer) ──proxy + Bearer──▶ Backend gateway
   ▲                    │
   └── httpOnly cookie ◀┘  (token KHÔNG lộ ra client)

Login: /auth/login (form) → POST BFF → IAM login + userInfo → seal session cookie → app

useApi dùng useRequestFetch để forward cookie khi SSR; lỗi chuẩn hoá về AppError. Chi tiết: BFF: /api/** đi đâu và Phiên đăng nhập.

Chế độ render — Hybrid (mặc định CSR)

SSR ≠ BFF. Cờ ssr: true vẫn bật để Nitro/BFF (/api, /auth, cookie httpOnly) chạy; nhưng phần render component mặc định là client-side vì Ant Design Vue (cssinjs) hỗ trợ SSR chưa tốt.

ssr: true,
routeRules: { '/**': { ssr: false } },  // app area CSR; BFF không đổi

Lý do đầy đủ, cách bật SSR cho từng route và những điểm phải tự xử lý khi bật: Chế độ render.

Quyết định cốt lõi

• antdv: cấm import trực tiếp (ESLint), bọc qua @tasco/ui; token qua ConfigProvider.
• Auth: abstract AuthProvider (mặc định form login qua IAM/BFF), inject qua layer; team chỉ khai báo permission.
• Versioning: Changesets + lockstep; breaking → major + migration guide.
• State: không dùng Pinia — useState, cookie và app.config.ts là đủ cho mô hình app quản trị.

Đọc tiếp

• Layer cung cấp gì — chi tiết từng phần layer mang theo.
• Cấu hình & biến môi trường — ba nơi cấu hình và bảng biến.
• Gọi backend — BFF, fetcher, hợp đồng dữ liệu.