doc_ai_frontend/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# 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:

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