# CLAUDE.md — Template cho dự án Vue 3
# Cách dùng: copy vào gốc repo thành CLAUDE.md, chạy /init trong Claude Code,
# merge kết quả /init vào khung này, điền [ĐIỀN], xoá dòng không đúng với repo.
# Nguyên tắc: <200 dòng, mỗi dòng phải kiểm chứng được.

## Lệnh thường dùng
- Cài deps: `npm ci` (KHÔNG dùng `npm install` trên CI)
- Dev server: `npm run dev`
- Test: `npm run test:unit` (Vitest) — chạy TRƯỚC mọi commit
- Lint + format: `npm run lint` (ESLint + Prettier) — phải pass trước khi tạo PR
- Build: `npm run build`; type-check: `npm run type-check` [ĐIỀN: xoá nếu không dùng TS]

## Kiến trúc
- Vue 3 + [ĐIỀN: Vite/Nuxt] + [ĐIỀN: Pinia/Vuex] + [ĐIỀN: Vue Router]
- Cấu trúc: `src/components` (dumb components), `src/views` (pages), `src/stores` (Pinia), `src/composables`, `src/api` (gọi backend qua [ĐIỀN: axios instance ở src/api/client.ts])
- State server-side dùng [ĐIỀN: TanStack Query/không] — KHÔNG tự chế cache trong component

## Quy ước code (bắt buộc)
- Composition API với `<script setup>` — KHÔNG dùng Options API cho code mới
- Component đặt tên PascalCase, file `.vue` trùng tên component; composable bắt đầu bằng `use`
- Props khai báo kèm type; emit khai báo tường minh bằng `defineEmits`
- KHÔNG gọi API trực tiếp trong component — đi qua `src/api/*`
- CSS: [ĐIỀN: Tailwind/scoped SCSS]; không viết style global mới khi chưa hỏi
- i18n: mọi text hiển thị đi qua [ĐIỀN: vue-i18n key], không hardcode chuỗi

## Test
- Vitest + Vue Test Utils; test đặt cạnh file: `Foo.vue` → `Foo.spec.ts`
- Component mới/bugfix bắt buộc kèm test; mock API bằng [ĐIỀN: msw/vi.mock]

## Git & PR
- Nhánh: `feature/<ticket>-mo-ta`, `fix/<ticket>-mo-ta`; KHÔNG commit thẳng vào `main`/`develop`
- Commit theo Conventional Commits (`feat:`, `fix:`, `refactor:`...)
- Trước khi tạo PR: lint pass + test pass + không còn `console.log`/code debug
- PR mô tả: thay đổi gì, cách test, ảnh hưởng UI (kèm screenshot nếu có)

## Definition of Done (feature chỉ được coi là xong khi)
1. Hành vi đúng theo spec ở mọi kịch bản mô tả, kể cả edge case đã nêu
2. `npm run test:unit` pass 100%; component/bugfix mới có test kèm theo
3. `npm run lint` không lỗi; không còn console.log/code debug
4. Hiển thị đúng ở cả viewport desktop và mobile
5. Text hiển thị đi qua i18n key, không hardcode

## Cấm
- Không sửa file trong `src/legacy/` [ĐIỀN: đường dẫn vùng cấm nếu có] khi chưa hỏi
- Không thêm dependency mới khi chưa được duyệt — đề xuất trước
- Không đưa secret/API key vào code; env qua `.env` (đã gitignore)