77 lines
3.2 KiB
Markdown
77 lines
3.2 KiB
Markdown
|
# CLAUDE.md
|
||
|
|
|
||
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
|
|
||
|
|
## Commands
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Development server
|
||
|
|
npm run dev
|
||
|
|
|
||
|
|
# Build
|
||
|
|
npm run build # production
|
||
|
|
npm run build:dev # development build (VITE_ENV=development)
|
||
|
|
npm run build:prod # production build (VITE_ENV=production)
|
||
|
|
|
||
|
|
# Type checking
|
||
|
|
npm run typecheck
|
||
|
|
|
||
|
|
# Linting
|
||
|
|
npm run lint
|
||
|
|
|
||
|
|
# Unit tests (vitest)
|
||
|
|
npm run test # run once
|
||
|
|
npm run test:watch # watch mode
|
||
|
|
|
||
|
|
# E2E tests (playwright)
|
||
|
|
npm run test:e2e
|
||
|
|
```
|
||
|
|
|
||
|
|
To run a single unit test file:
|
||
|
|
```bash
|
||
|
|
npx vitest run src/components/__tests__/AuthModal.test.tsx
|
||
|
|
```
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
### Provider Tree
|
||
|
|
`main.tsx` wraps everything in: `BrowserRouter → AuthProvider → LanguageProvider → AppRouter`
|
||
|
|
|
||
|
|
### Routing
|
||
|
|
Only two routes (`src/routes/AppRouter.tsx`):
|
||
|
|
- `/` → `App` (main app)
|
||
|
|
- `/auth/google/callback` → `AuthCallbackPage` (Google OAuth callback handler)
|
||
|
|
|
||
|
|
### Auth System
|
||
|
|
- **`AuthContext.tsx`** — React context providing `signIn`, `signUp`, `beginGoogleOAuth`, `completeGoogleOAuth`, `signOut`. Uses `useReducer` with `authMachine.ts`.
|
||
|
|
- **`authMachine.ts`** — Pure reducer + state types (`AuthPhase`, `AuthState`, `AuthAction`). No side effects — all async logic lives in `AuthContext`.
|
||
|
|
- **`authService.ts`** — Calls backend API for login/register/Google OAuth/user info. Decodes JWT payload client-side to extract `UserInfo`. Handles session restore from `localStorage`.
|
||
|
|
- **`lib/api.ts`** — `http` client wrapper with `tokenManager` (stores JWT in `localStorage` under key `texpixel_token`). Adds `Authorization` header automatically. Throws `ApiError` for non-success business codes.
|
||
|
|
|
||
|
|
### Environment / API
|
||
|
|
- **`src/config/env.ts`** — Switches API base URL based on `VITE_ENV` env var:
|
||
|
|
- `development`: `https://cloud.texpixel.com:10443/doc_ai/v1`
|
||
|
|
- `production`: `https://api.texpixel.com/doc_ai/v1`
|
||
|
|
- The API uses a custom response envelope: `{ request_id, code, message, data }`. Success is `code === 200` (some endpoints also accept `0`).
|
||
|
|
|
||
|
|
### Main App Flow (`App.tsx`)
|
||
|
|
Three-panel layout: `LeftSidebar | FilePreview | ResultPanel`
|
||
|
|
|
||
|
|
Core data flow:
|
||
|
|
1. On auth, `loadFiles()` fetches paginated task history from `/task/list`
|
||
|
|
2. File upload goes: compute MD5 → get OSS pre-signed URL (`/oss/signature_url`) → PUT to OSS → create task (`/formula/recognition`) → poll every 2s for result
|
||
|
|
3. Results cached in `resultsCache` ref (keyed by `task_id`) to avoid redundant API calls
|
||
|
|
4. Guest users get 3 free uploads tracked via `localStorage` (`texpixel_guest_usage_count`)
|
||
|
|
|
||
|
|
### Internationalization
|
||
|
|
`LanguageContext.tsx` supports `en` / `zh`. Language is auto-detected via IP (`lib/ipLocation.ts`) on first visit, persisted to `localStorage` on manual switch. All UI strings come from `lib/translations.ts` via `const { t } = useLanguage()`.
|
||
|
|
|
||
|
|
### Key Type Definitions
|
||
|
|
- `src/types/api.ts` — All API request/response types, `TaskStatus` enum, `ApiErrorCode` enum, `ApiErrorMessages` map
|
||
|
|
- `src/types/index.ts` — Internal app types (`FileRecord`, `RecognitionResult`)
|
||
|
|
|
||
|
|
### Tests
|
||
|
|
- Unit tests: `src/components/__tests__/` and `src/contexts/__tests__/`, run with vitest + jsdom + `@testing-library/react`
|
||
|
|
- E2E tests: `e2e/` directory, run with Playwright
|
||
|
|
- Setup file: `src/test/setup.ts`
|