前端架构

KanjiIQ前端是一个Flutter Web应用，由Nginx提供服务。支持离线学习、自动区域检测和51种UI语言。

构建流水线

graph LR
    S[Flutter Source] --> GL[flutter gen-l10n<br/>Generate 51 ARB files]
    GL --> B[flutter build web<br/>--release]
    B --> N[Nginx Alpine<br/>Static Serve]

前端构建为多阶段Docker镜像：

1. 构建阶段（Ubuntu 22.04）：安装Flutter SDK，生成本地化文件，构建发布版Web资源
2. 生产阶段（Nginx Alpine）：提供静态文件服务，支持gzip压缩、缓存和SPA路由

核心技术

技术	版本	用途
Flutter	最新稳定版	UI框架
Provider	^6.1.1	状态管理
GoRouter	^13.0.0	声明式路由
sqflite	^2.3.2	本地SQLite离线缓存
connectivity_plus	^5.0.2	网络状态检测
SharedPreferences	^2.2.2	持久化键值存储
flutter_animate	^4.5.0	UI动画

应用结构

frontend/lib/
├── main.dart                    # App entry point, Provider setup
├── models/                      # Data models (Kanji, Vocabulary)
├── providers/                   # State management
│   └── study_provider.dart      # Flashcard session state
├── repositories/                # Data access layer
│   ├── kanji_repository.dart    # Cache-first kanji fetching
│   └── vocabulary_repository.dart
├── screens/                     # UI screens
│   ├── home_screen.dart         # Language & level selection
│   ├── study_screen.dart        # Flashcard presentation
│   └── results_screen.dart      # Session summary
├── services/                    # Business logic
│   ├── api_service.dart         # REST API client
│   ├── database_helper.dart     # Local SQLite operations
│   ├── locale_detector.dart     # Device locale detection
│   ├── locale_preferences.dart  # Language preference management
│   ├── connectivity_service.dart # Online/offline detection
│   └── sync_service.dart        # Background data synchronization
└── l10n/                        # Localization
    ├── app_en.arb               # English (template)
    ├── app_ja.arb               # Japanese
    └── ... (51 ARB files)

离线优先架构

KanjiIQ无需互联网连接即可使用，采用缓存优先的数据策略：

graph TD
    A[User requests data] --> B{Local cache<br/>available?}
    B -->|Yes| C[Return cached data]
    B -->|No| D{Online?}
    D -->|Yes| E[Fetch from API]
    D -->|No| F[Show offline message]
    E --> G[Store in SQLite]
    G --> C
    C --> H[Background sync<br/>when online]

• SQLite 在本地存储汉字和词汇，支持离线访问
• ConnectivityService 监控网络状态变化
• SyncService 在网络恢复时执行后台同步
• SharedPreferences 缓存区域配置，有效期7天

Nginx配置

Nginx服务器（nginx.frontend.conf）负责处理：

• SPA路由：所有路由回退到index.html，支持Flutter的客户端路由
• API代理：/api/请求被代理到localhost:8080（同一Pod中的后端容器）
• Gzip压缩：对文本、CSS、JS、JSON和SVG启用压缩
• 缓存控制：版本化静态资源缓存1年，index.html不缓存
• 安全头：X-Frame-Options、X-Content-Type-Options、Referrer-Policy
• 健康检查：/health端点，用于Kubernetes探针