aplp.frontend.web/docs/CONVENTIONS.md

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