# CLAUDE.md

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

## Commands

### Development
- **`npm run ios`** - Build and run on iOS Simulator (iOS-only deployment)

### Testing
- Automated testing is minimal; complex logic should include Jest + React Native Testing Library specs under `__tests__/` directories or alongside modules

## Architecture

### Core Stack
- **Framework**: React Native (Expo Prebuild/Ejected) with TypeScript
- **Navigation**: Expo Router with file-based routing in `app/` directory
- **State Management**: Redux Toolkit with domain-specific slices in `store/`
- **Styling**: Custom theme system with light/dark mode support

### Directory Structure
- **`app/`** - Expo Router screens; tab flows in `app/(tabs)/`, feature-specific pages in nested directories
- **`store/`** - Redux slices organized by feature (user, nutrition, workout, etc.)
- **`services/`** - API services, backend integration, and data layer logic
- **`components/`** - Reusable UI components and domain-specific components
- **`hooks/`** - Custom React hooks including typed Redux hooks (`hooks/redux.ts`)
- **`utils/`** - Utility functions (health data, notifications, fasting, etc.)
- **`contexts/`** - React Context providers (ToastContext, MembershipModalContext)
- **`constants/`** - Route definitions (`Routes.ts`), colors, and app-wide constants
- **`types/`** - TypeScript type definitions
- **`assets/`** - Images, fonts, and media files
- **`ios/`** - iOS native code and configuration

### Navigation
- **File-based routing**: Pages defined by file structure in `app/`
- **Tab navigation**: Main tabs in `app/(tabs)/` (Explore, Coach, Statistics, Challenges, Personal, Fasting)
- **Route constants**: All route paths defined in `constants/Routes.ts`
- **Nested layouts**: Feature-specific layouts in nested directories (e.g., `app/nutrition/_layout.tsx`)

### State Management
- **Redux slices**: Feature-based state organization (17+ slices including user, nutrition, workout, mood, etc.)
- **Auto-sync middleware**: Listener middleware automatically syncs checkin data changes to backend
- **Typed hooks**: Use `useAppSelector` and `useAppDispatch` from `hooks/redux.ts` for type safety
- **Persistence**: AsyncStorage for local data persistence

### UI System
- **Themed components**: `ThemedText`, `ThemedView` with dynamic color scheme support
- **Custom icons**: `IconSymbol` component for iOS SF Symbols
- **UI library**: Reusable components in `components/ui/`
- **Colors**: Centralized in `constants/Colors.ts`
- **Safe areas**: `useSafeAreaTop` and `useSafeAreaWithPadding` hooks for device-safe layouts

### Data Layer
- **API client**: Centralized in `services/api.ts` with interceptors and error handling
- **Service modules**: Domain-specific services in `services/` (nutrition, workout, notifications, etc.)
- **Background tasks**: Managed by `backgroundTaskManager.ts` for sync operations
- **Local storage**: AsyncStorage for offline-first data persistence

### Native Integration
- **HealthKit**: Health data integration in `utils/health.ts` and `utils/healthKit.ts`
- **Apple Authentication**: Configured in Expo settings
- **Camera & Photos**: Food recognition and posture assessment features
- **Push Notifications**: `services/notifications.ts` with background task support
- **Haptic Feedback**: `utils/haptics.ts` for user interactions
- **Quick Actions**: Expo quick actions integration

### Context Providers
- **ToastContext** - Global toast notification system
- **MembershipModalContext** - VIP membership feature access control

## Key Architecture Patterns

- **Redux Auto-sync**: Listener middleware in `store/index.ts` automatically syncs checkin data changes to backend
- **Type-safe Navigation**: Expo Router with TypeScript for compile-time route safety
- **Authentication Flow**: `pushIfAuthedElseLogin` function handles auth-protected navigation
- **Theme System**: Dynamic theming with light/dark mode and color tokens
- **Service Layer**: Centralized API client with interceptors and error handling
- **Background Sync**: Automatic data synchronization via background task manager

## Development Conventions

### Import Patterns
- **Absolute imports**: Use `@/` prefix for all internal imports (e.g., `@/store`, `@/services/api`)
- **Alias configuration**: Defined in `tsconfig.json` paths

### Redux Patterns
- **Feature slices**: Each feature has its own slice (userSlice.ts, nutritionSlice.ts, etc.)
- **Typed hooks**: Always use `useAppSelector` and `useAppDispatch` from `hooks/redux.ts`
- **Async actions**: Use Redux Toolkit thunks for async operations
- **Auto-sync**: Listener middleware handles automatic data synchronization

### Naming Conventions
- **Components**: PascalCase (e.g., `ThemedText.tsx`, `FitnessRingsCard.tsx`)
- **Hooks**: camelCase with "use" prefix (e.g., `useAppSelector`, `useSafeAreaTop`)
- **Utilities**: camelCase (e.g., `health.ts`, `notificationHelpers.ts`)
- **Screen files**: kebab-case (e.g., `ai-posture-assessment.tsx`, `nutrition-label-analysis.tsx`)
- **Constants**: UPPER_SNAKE_CASE for values, PascalCase for types

### Code Style
- **ESLint**: Configured with `eslint-config-expo` in `eslint.config.js`
- **Formatting**: 2 spaces, trailing commas, single quotes (Prettier defaults)
- **TypeScript**: Strict mode enabled, use proper type annotations

### Navigation & Routing
- **Route constants**: Always use constants from `constants/Routes.ts` for navigation
- **Auth guards**: Implement using `useAuthGuard` hook for protected features
- **Typed routes**: Leverage Expo Router's TypeScript integration

### Testing Guidelines
- **Minimal automated tests**: Add Jest + React Native Testing Library for complex logic
- **HealthKit testing**: Requires real device; verify on iOS Simulator when possible
- **Integration tests**: Include reproduction steps and logs in PR descriptions

### iOS Development
- **Native changes**: Update `ios/` directory and re-run `npm run ios` after modifying Swift or entitlements
- **HealthKit**: Requires entitlements configuration; coordinate with release engineering
- **App signing**: Keep bundle IDs consistent with `app.json` and iOS project configuration
- **App Groups**: Required for widget and quick actions integration

### Git Workflow
- **Conventional Commits**: Use `feat`, `fix`, `chore` prefixes with optional scope
- **PR descriptions**: Include problem, solution, test evidence (screenshots, commands), iOS setup notes
- **Change grouping**: Group related changes; avoid bundling unrelated features
- 总是先总结方案,等我确认之后,再进行实现