tashow-manager/CLAUDE.md

CLAUDE.md

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

Project Overview

This is a multi-tenant service management platform ("百业到家") built with Ant Design Pro, React 19, TypeScript, and UmiJS Max framework. The application uses dynamic routing loaded from a backend API and implements a comprehensive permission system.

Development Commands

# Start development server (with mocks)
pnpm dev
# or
pnpm start

# Start development server (without mocks, connects to backend)
pnpm start:dev

# Build for production
pnpm build

# Lint (Biome + TypeScript check)
pnpm lint

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Type check only
pnpm tsc

Important: This project uses pnpm as the package manager, not npm or yarn.

Architecture

Dynamic Routing System

Routes are not statically defined in config/routes.ts (most routes are commented out). Instead, routes are dynamically loaded from the backend API:

1. On app initialization, getInfo() fetches user permissions and menu structure
2. patchClientRoutes() in src/app.tsx transforms backend menu data into UmiJS routes
3. loopMenuItem() in src/utils/menuUtils.tsx recursively converts menu items to route objects
4. Routes are lazy-loaded using React.lazy(() => import('@/pages/${component}'))

When adding new pages: Create the page component in src/pages/, then configure the route in the backend system (not in code).

Multi-Tenant Architecture

Every API request includes a tenant-id header. Tenant information is:

• Stored in web-storage-cache with key CACHE_KEY.TenantId
• Set during login via setTenantId()
• Automatically added to all requests by the request interceptor in src/app.tsx

Authentication Flow

1. User logs in with tenant name, username, and password (password is RSA encrypted via JSEncrypt)
2. Backend returns accessToken and refreshToken
3. Tokens stored in web-storage-cache (see src/utils/auth.ts)
4. All requests include Authorization: Bearer ${accessToken} header
5. On 401 response, automatically attempts token refresh using refreshToken
6. If refresh fails, redirects to login page

Token refresh logic is in src/requestErrorConfig.ts with request queuing to prevent duplicate refresh attempts.

Request Interceptors

All API requests are automatically modified (see src/app.tsx):

• API prefix: /admin-api is prepended to all URLs (unless already present)
• Headers: Authorization, tenant-id, and Accept headers are added
• Parameter serialization: Arrays are serialized specially:
  • createTime arrays become createTime[0] and createTime[1]
  • Other arrays become key[] format

Caching Strategy

Uses web-storage-cache library (see src/hooks/web/useCache.ts):

• CACHE_KEY.USER: Current user info
• CACHE_KEY.ROLE_ROUTERS: Dynamic menu/route data
• CACHE_KEY.ACCESS_TOKEN / CACHE_KEY.REFRESH_TOKEN: Auth tokens
• CACHE_KEY.DICT_CACHE: Dictionary/enum data loaded on app init
• CACHE_KEY.LoginForm: Remember me functionality (password encrypted)

State Management

• UmiJS Model Plugin: For global state (see src/app.tsx - initialState)
• Custom Hooks: In src/hooks/stores/ (e.g., useDictStore for dictionary management)
• Web Storage Cache: For persistent data across sessions

Project Structure

src/
├── pages/           # Feature pages organized by domain
│   ├── ai/         # AI model and sample management
│   ├── prod/       # Product and category management
│   ├── system/     # System admin (users, roles, menus, tenants, logs, messages)
│   ├── trade/      # Order and sales management
│   └── user/       # Login page
├── services/       # API service layer (mirrors page structure)
├── components/     # Reusable components
│   ├── Draggable/  # Drag-and-drop components using @dnd-kit
│   ├── Upload/     # File/image/video upload components
│   ├── GroupTag/   # Tag management components
│   └── Tinymce/    # Rich text editor wrapper
├── hooks/          # Custom React hooks
│   ├── antd/       # Ant Design related hooks
│   ├── stores/     # State management hooks
│   └── web/        # Web utilities (cache, etc.)
├── utils/          # Utility functions
│   ├── auth.ts     # Token and tenant management
│   ├── menuUtils.tsx  # Dynamic route conversion
│   ├── dict.ts     # Dictionary/enum utilities
│   └── tree.ts     # Tree data structure helpers
├── constants/      # Shared constants and enums
├── locales/        # i18n translations (zh-CN default)
└── app.tsx         # App initialization and runtime config

Environment Configuration

Multiple environment files:

• .env.local - Local overrides (gitignored)
• .env.dev - Development environment
• .env.prod - Production environment

Proxy configuration in config/proxy.ts:

• dev: Points to local backend (currently http://192.168.1.89:48080)
• test: Points to test environment
• pre: Points to pre-production environment

Switch environments using UMI_ENV:

cross-env UMI_ENV=dev pnpm start    # Development
cross-env UMI_ENV=test pnpm start   # Test
cross-env UMI_ENV=pre pnpm start    # Pre-production

Code Conventions

Linting

• Uses Biome (not ESLint) for linting and formatting
• Configured in biome.json
• Pre-commit hook runs Biome via lint-staged

Commit Messages

• Uses commitlint with conventional commits
• Enforced via Husky pre-commit hook
• Format: type(scope): subject (e.g., feat: add user management)

Component Patterns

• ProTable: Use EnhancedProTable wrapper for common table functionality
• Forms: Use DrawerForm or ModalForm from @ant-design/pro-components
• File Uploads: Use custom UploadImages or UploadVideo components in src/components/Upload/
• Rich Text: Use Tinymce component wrapper (TinyMCE is in public/tinymce/)

Service Layer

• All API calls go through src/services/
• Use UmiJS request from @umijs/max (configured in src/app.tsx)
• Response format: { code: number, data: any, msg: string }
• Success when code === 0

Common Patterns

Adding a New Page

1. Create page component in src/pages/{domain}/{feature}/index.tsx
2. Create corresponding service in src/services/{domain}/{feature}/index.ts
3. Configure the menu/route in the backend system (not in code)
4. The route will automatically appear after backend configuration

Working with Dictionaries/Enums

Dictionaries are loaded on app init and cached:

import { useDictStore } from '@/hooks/stores/dict';

const dictStore = useDictStore();
const dictData = dictStore.getDictByType('dict_type_key');

File Uploads

Media files are uploaded via src/services/infra/file/index.ts or src/services/infra/media/index.ts. Use the Upload components which handle the API integration.

Testing

• Jest configured with jest.config.ts
• Test files should be colocated with components or in __tests__ directories
• Run single test: pnpm test -- path/to/test.spec.ts

Important Notes

• Node version: Requires Node.js >= 20.0.0 (see package.json engines)
• React 19: Uses React 19 with @ant-design/v5-patch-for-react-19 compatibility patch
• Mako bundler: Uses UmiJS Mako for faster builds (configured in config/config.ts)
• Mock data: Located in mock/ directory, enabled by default in dev mode
• TinyMCE: Static files in public/tinymce/, Chinese language pack included