# CLAUDE.md

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

## Project Overview

This is a Flutter news app (`news_app`) that displays news, videos, activities, and topics. The app uses:
- **Flutter SDK 3.7.2+**
- **Riverpod** for state management
- **Dio** for HTTP requests
- **go_router** for navigation
- **flutter_screenutil** for responsive design (375x812 design size)
- **EasyRefresh** for pull-to-refresh and load-more functionality

## Development Commands

```bash
# Get dependencies
flutter pub get

# Run the app
flutter run

# Run on specific device (use `flutter devices` to list)
flutter run -d <device-id>

# Run on iOS simulator (auto-detect or use device-id)
flutter run -d ios

# Build APK (release)
flutter build apk --release

# Build APK with custom naming (uses build.py script)
python3 build.py

# Run tests
flutter test

# Analyze code
flutter analyze

# Generate code (for build_runner dependencies)
flutter pub run build_runner build --delete-conflicting-outputs

# Generate assets (for flutter_gen)
flutter pub run build_runner watch --delete-conflicting-outputs
```

## Project Structure

```
lib/
├── main.dart              # App entry point, router config, global providers
├── constant/              # Configuration constants (API endpoints, config)
├── http/                  # HTTP layer (Dio wrapper, exception handling)
├── model/                 # Data models (JSON parsing with fromJson/toJson)
├── provider/              # Riverpod providers (state management)
├── ui/                   # UI pages (news, video, activity, topic, user, login, search)
├── util/                  # Utilities (toast, cache, permissions, share, etc.)
├── widget/                # Reusable widgets
├── event/                 # Event bus events (e.g., LogoutEvent)
├── extension/             # Dart extensions
└── gen/                  # Generated assets (from flutter_gen)
```

## Architecture

### State Management (Riverpod)

The app uses Riverpod 2.x with `Notifier` and `FamilyNotifier` APIs (not deprecated `StateNotifierProvider`).

Common patterns:

1. **Global Providers** - defined in `main.dart`:
   - `globalUserProvider` - current user session
   - `globalThemeProvider` - theme mode (light/dark)
   - `grayProvider` - grayscale mode toggle

2. **Feature Providers** - located in `lib/provider/`, typically named `[feature]_provider.dart`:
   - Each provider extends `Notifier<State>` or `FamilyNotifier<State, Arg>`
   - State classes use immutable pattern with `copyWith()` method
   - Example: `NewsNotifier` in `news_provider.dart`

3. **Usage in widgets:**
   ```dart
   // Read state
   final state = ref.watch(newsProvider(index));
   // Call provider methods
   ref.read(newsProvider(index).notifier).fetchNewsItemList(1);
   ```

### HTTP Layer (Dio)

`lib/http/http_util.dart` wraps Dio for all API calls:

- Singleton pattern: `HttpUtil()` instance
- Base URL: configured in `lib/constant/api_const.dart`
- Methods: `get()`, `post()`, `put()`, `delete()`, `upload()`, `download()`
- Interceptors: adds `uuid` header for authentication, shows error toasts
- Response handling: returns `data['data']` or throws `MyException` on `code != 200`
- Error 401 triggers `LogoutEvent` via EventBus

**API endpoints** are defined in `lib/constant/api_const.dart`.

### Navigation (go_router)

Router configuration in `lib/main.dart` (`_routerConfig`):

- Routes defined as `GoRoute` with `path` and `builder`/`pageBuilder`
- Page transitions use `CustomTransitionPage` with fade animations
- Parameters passed via `state.extra` (not query params)
- Example routes: `/login`, `/main`, `/news/detail`, `/video/detail`

### Models

All models in `lib/model/` use JSON serialization:
- `fromJson(Map<String, dynamic> json)` - parses from API response
- `toJson()` - serializes for API requests (if needed)

### EventBus

Global EventBus in `lib/constant/config.dart`:
- Used for cross-component events (e.g., `LogoutEvent`)
- Example: `eventBus.fire(LogoutEvent(jumLogin: true))`

## Key Patterns

### User Authentication

- User UUID stored in `SharedPreferences` (see `lib/util/shared_prefs_instance_util.dart`)
- UUID sent as `uuid` and `Authorization-M` headers in all requests
- Global `uuid` variable in `lib/constant/config.dart`
- Login state managed by `globalUserProvider`

### Responsive Design

All sizes use `flutter_screenutil`:
- Design size: 375x812
- Use `20.w`, `30.h`, `12.sp` for width/height/font-size
- Wrap root with `ScreenUtilInit`

### Refresh & Pagination

- `EasyRefresh` for pull-to-refresh and load-more
- Common pattern: fetch with `pageNum` parameter, append results on `pageNum > 1`

### Grayscale Mode

Controlled by `grayProvider`:
- Wraps app in `ColorFiltered` with grayscale matrix when enabled
- Configured via `enableProxy` flag in `lib/constant/config.dart` (also controls packet capture proxy)

### Asset References

Use generated assets from `lib/gen/assets.gen.dart`:
```dart
Image.asset(Assets.images.navNewsSelect.path)
```

### Video Playback

The app includes video content using:
- `better_player_plus` - Video player for streaming/local videos
- `flutter_swiper_view` - Carousel/swiper for banners and image lists
- Video pages handle autoplay, quality selection, and fullscreen modes

### WeChat Integration

Uses `fluwx` package for WeChat-related features:
- Share content to WeChat moments/friends
- WeChat login (if configured with app credentials

## API Base URL

Current base URL: `https://app.xhrbxxf.com/` (configured in `lib/constant/api_const.dart`)

## Testing

Tests are minimal (`test/widget_test.dart` contains a basic template).
When adding tests, follow Flutter testing conventions and use `flutter test` to run.

## Proxy/Debugging

- Enable packet capture proxy by setting `enableProxy = true` in `lib/constant/config.dart`
- Proxy address: `192.168.3.21:9090` (hardcoded)
- PrettyDioLogger enabled in debug mode for request logging