feat: add guide

docs/CONVENTIONS.md

@@ -0,0 +1,82 @@
+# APLP Frontend — Conventions
+
+| | |
+| --- | --- |
+| **Status** | Phase 0 hoàn tất |
+
+## 1. Language & Tooling
+
+- **TypeScript** cho toàn bộ code. Không dùng `any` tùy tiện; ưu tiên explicit types.
+- Lint: **oxlint** (đã confirm Phase 0); format: **Prettier**.
+- Convention: file `.tsx` cho React components; kiểu dùng interface cho props.
+
+## 2. Naming
+
+| Loại | Quy ước |
+| --- | --- |
+| Component | PascalCase (`CourseCard.tsx`) |
+| Hook | camelCase, prefix `use` (`useLearningProgress.ts`) |
+| Page/route | PascalCase trong `pages/` |
+| API function | camelCase (`fetchCourseDetail`) |
+| Types/interface | PascalCase (`CourseDetailDto`, `ApiError`) |
+
+## 3. Component Rules
+
+- Component nhỏ, single responsibility.
+- Props dùng interface; optional props explicit.
+- Logic phức tạp nên tách vào hooks.
+- Components dùng chung đặt `src/shared/components`; feature-specific vào `features/<feature>/components`.
+- Không đặt business logic vào JSX.
+
+## 4. State Management
+
+- **Server state** → TanStack Query (query keys chuẩn: `['course', id]`).
+- **UI/local state** → `useState`; nếu cần chia sẻ toàn app → Zustand store.
+- Không đặt server data vào Zustand khi đã có React Query (tránh trùng source of truth).
+- Tên store: domain concept (`useLearnerStore`).
+
+## 5. API Layer
+
+- Gọi backend qua `src/api` wrapper. Không gọi `fetch`/axios trực tiếp tại component.
+- Response mapping/error handling nằm trong api layer.
+- Có hằng số endpoint riêng, không đặt URL rải rác.
+
+## 6. Error & Loading States
+
+- Mọi view fetch/save cần xử lý: loading, empty, error, success.
+- Dùng shared components (Spinner, EmptyState, ErrorState / ErrorBoundary).
+- Hiển thị lỗi user-friendly từ `ApiError` của backend; không hiện stack trace.
+
+## 7. Styling
+
+- Dùng design tokens/theme (xác nhận stack Phase 0).
+- Không hard-code color/margin lộn xộn; ưu tiên class utility/component thống nhất.
+- Responsive theo grid/breakpoints chuẩn.
+
+## 8. Testing
+
+- Unit test components/hooks: Vitest.
+- Render test với testing-library.
+- E2E (Playwright) — optional, đánh giá sau.
+- Test file đặt cạnh source (`Component.test.tsx`) hoặc `__tests__/` — chọn 1 để thống nhất.
+
+## 9. Git & Collaboration
+
+- Commit nhỏ, message rõ (theo style repo khi setup lại).
+- Dùng feature branch + review.
+- Lint + typecheck + test chạy qua (lệnh chuẩn `npm run lint`, `npm run typecheck`, `npm test`) trước khi merge.
+
+## 10. Security
+
+- **Không** lưu secret/token vào code hay log.
+- Không put credentials vào env file committed (`.env` → `.env.example`).
+- Không render user content bằng `dangerouslySetInnerHTML` trừ khi đã sanatize.
+
+## 11. Open Questions
+
+| ID | Question | Status |
+| --- | --- | --- |
+| CON-001 | ESLint config (airbnb/custom)? | **Resolved: oxlint (default config)** |
+| CON-002 | Path alias (`@/`)? | **Resolved: có (`@` → `src`)** |
+| CON-003 | Test file location convention? | **Resolved: đặt cạnh source (`Component.test.tsx`)** |
+| CON-004 | Storybook có cần? | Open |