demo/xinhuaribao/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 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

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

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

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