|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with the RAGFlow frontend (`web/`). |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +RAGFlow frontend is a React/TypeScript application built with UmiJS: |
| 8 | +- **Components**: shadcn/ui |
| 9 | +- **Styling**: Tailwind CSS |
| 10 | +- **State**: Zustand |
| 11 | +- **Data Fetching**: TanStack Query (React Query) |
| 12 | +- **i18n**: react-i18next |
| 13 | + |
| 14 | +## Common Commands |
| 15 | + |
| 16 | +```bash |
| 17 | +npm install |
| 18 | +npm run dev # Development server |
| 19 | +npm run build # Production build |
| 20 | +npm run lint # ESLint |
| 21 | +npm run test # Jest tests |
| 22 | +``` |
| 23 | + |
| 24 | +## Development Conventions |
| 25 | + |
| 26 | +### CSS and Layout Debugging |
| 27 | +When fixing CSS/layout issues (especially flex truncation, ellipsis, or element sizing), **always inspect the full parent hierarchy** for `flex-shrink`, `min-width`, and `overflow` constraints before applying fixes like `min-w-0`. Do not repeatedly apply the same fix without verifying the root cause. |
| 28 | +- Before editing, explain: (1) the full flex/container hierarchy from the target element up to the nearest non-flex ancestor, (2) what constraint is actually causing the bug, and (3) how the proposed fix addresses that root cause. |
| 29 | + |
| 30 | +### Scope and Boundaries |
| 31 | +Respect explicit boundaries from the user. If the user says **"only fix the selected line"** or **"do not touch shared types/files"**, follow that instruction exactly. Do not investigate unrelated errors, modify shared schemas (e.g., `LlmSettingFieldSchema`), or refactor other files without confirmation. If a change outside the described scope seems necessary, ask for permission first. |
| 32 | + |
| 33 | +### Internationalization (i18n) |
| 34 | +For translation tasks, add keys **only to the explicitly requested language files** (commonly `src/locales/zh.ts` and `src/locales/en.ts`). Do not auto-propagate changes to all language files unless the user explicitly asks. |
| 35 | +- **Style for `en.ts`**: Sentence case — first word capitalized, rest lowercase (e.g., `referenceAnswer: 'Reference answer'`). Proper nouns remain as-is. |
| 36 | + |
| 37 | +### React Component Refactoring |
| 38 | +When refactoring or extracting components, **verify layout behavior after each structural change** (especially `flex-1`, conditional rendering, or flex direction changes). Check that existing buttons, alignment, and responsive behavior remain intact. After extraction, verify: (1) all original props and behavior are preserved, (2) layout in parent contexts is identical, and (3) no syntax or type errors were introduced. |
| 39 | + |
| 40 | +### State Management and Data Fetching |
| 41 | +For React Query / cache invalidation bugs, **carefully compare query keys across all consuming components and mutation hooks**. Mismatched keys (e.g., with/without `refreshCount`) are a common root cause of stale data or duplicate requests. |
| 42 | +- Systematically: (1) list every component/hook that calls `useQuery` for this data, (2) compare their query keys character-for-character, (3) check every mutation's `onSuccess` for cache invalidation, and (4) verify no parent re-renders are remounting the observer. |
| 43 | + |
| 44 | +### React Patterns and Conventions |
| 45 | +- **Prefer `requestAnimationFrame` or `useLayoutEffect`** over `setTimeout(..., 0)` for focus or DOM measurement operations. |
| 46 | +- **Prefer `useTranslation` from `react-i18next`** over project-wrapped utilities like `useTranslate`. |
| 47 | +- Extract complex logic into hooks or utils; keep components lean. |
| 48 | +- Use `PascalCase` for constants and component names. |
| 49 | +- Avoid duplicating component structures in JSX; favor render props or reusable components. |
0 commit comments