refactor: cleanup

Author: kamiya4047

CLAUDE.md

@@ -0,0 +1,84 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+DPIP (Disaster Prevention Information Platform) — a Flutter app for Taiwan earthquake early warning and disaster information, integrating TREM-Net and CWA data.
+
+## Commands
+
+```bash
+# Install dependencies
+flutter pub get --no-example
+
+# Format
+dart format .
+
+# Lint
+dart analyze .
+
+# Code generation (required after editing routes, @JsonSerializable, or @freezed models)
+dart run build_runner build
+
+# Update translations
+bash tools/update_translations.sh
+
+# Run
+flutter run
+
+# Build
+flutter build apk --release
+flutter build ios --release
+```
+
+There is no test suite.
+
+## Architecture
+
+**State management:** Provider (`ChangeNotifier`). Global providers are registered in `lib/core/providers.dart`:
+- `DpipDataModel` — earthquake/weather data
+- `SettingsLocationModel`, `SettingsMapModel`, `SettingsNotificationModel`, `SettingsUserInterfaceModel`
+
+**Routing:** go_router with type-safe routes via `@TypedGoRoute`. Routes are defined in `router.dart` and code-generated into `router.g.dart`. Run `build_runner` after route changes.
+
+**Feature modules** live under `lib/app/` (home, map, settings, changelog, debug, welcome). Each is self-contained with its own widgets subfolder.
+
+**API layer** (`lib/api/`): Dio HTTP client with caching. Models use `@JsonSerializable` + `@freezed` — regenerate with `build_runner` after changes.
+
+**Core services** (`lib/core/`): FCM, GPS, local notifications, EEW logic (`eew.dart`), compass, i18n, device info.
+
+**Assets:** JSON data files are gzip-compressed (`*.json.gz`) and decompressed at runtime. GLSL shaders (`fog.frag`, `thunderstorm.frag`) are used for map effects.
+
+## Key Conventions
+
+- **Settings naming:** Notification settings use numbered prefixes — `(1.eew)`, `(2.earthquake)`, `(3.weather)`, `(4.tsunami)`, `(5.basic)` — to control display order.
+- **Linting:** Extends `package:lint/strict.yaml`. Line width 100, preserve trailing commas, prefer single quotes.
+- **Documentation:** Every public member must have a doc comment (`///`). Every file must have a top-level library doc comment (`/// ...` before any `library` or first declaration). Follow Effective Dart: document usage and behavior from the caller's perspective, not internal implementation. Use `[...]` for code references, avoid restating the name.
+- **Dot shorthand:** Always use Dart dot shorthand (e.g., `.value` instead of `EnumType.value`) wherever the type can be inferred from context.
+- **Widget extraction:** When a build method nests too deeply, extract the subtree into a private widget class (`_FooWidget`) in the same file rather than keeping it inline.
+- **Class member order** (top to bottom), within each group sort alphabetically `A→Z` then `a→z`:
+  1. Class fields
+  2. Primary constructor
+  3. Named constructors
+  4. Uninitialized variables / private fields
+  5. Private methods
+  6. Public methods
+  7. Overriding methods — widgets follow lifecycle order: `initState` → `build` → `dispose`
+  8. Static fields
+  9. Static members
+- **Extensions:** Always prefer extension methods from `lib/utils/extensions/` over verbose equivalents. Avoid `.of(context)` calls — use `BuildContext` extensions instead:
+  - `context.theme` → `Theme.of(context)`
+  - `context.colors` → `Theme.of(context).colorScheme`
+  - `context.texts` → `Theme.of(context).textTheme`
+  - `context.dimension` → `MediaQuery.sizeOf(context)`
+  - `context.padding` → `MediaQuery.paddingOf(context)`
+  - `context.brightness` → `MediaQuery.platformBrightnessOf(context)`
+  - `context.navigator` → `Navigator.of(context)`
+  - `context.scaffoldMessenger` → `ScaffoldMessenger.of(context)`
+  - `context.router` → `GoRouter.of(context)`
+  - `context.popUntil(path)` → `GoRouter.of(context).popUntil(path)`
+  - `context.bottomSheetConstraints` → Material 3 bottom sheet constraints
+- **Generated files** (`**.freezed.dart`, `**.g.dart`) are excluded from analysis — do not edit them manually.
+- **Localization:** Uses `i18n_extension`. Translations are managed via Crowdin; only zh-Hant is updated locally via the translation script.
+- **Maps:** MapLibre GL with multiple layer managers. Dynamic color (Material You) via `dynamic_color`.

analysis_options.yaml

@@ -15,5 +15,5 @@ linter:
     public_member_api_docs: warning
 
 formatter:
-  page_width: 80
+  page_width: 100
   trailing_commas: preserve

lib/app.dart

@@ -78,7 +78,7 @@ class _DpipAppState extends State<DpipApp> with WidgetsBindingObserver {
       WidgetsBinding.instance.addPostFrameCallback((_) {
         final ctx = router.routerDelegate.navigatorKey.currentContext;
         if (ctx != null && mounted) {
-          ctx.go(WelcomePermissionPage.route);
+          WelcomePermissionsRoute().go(context);
         }
       });
     }
@@ -95,13 +95,7 @@ class _DpipAppState extends State<DpipApp> with WidgetsBindingObserver {
 
     switch (widget.initialShortcut) {
       case 'monitor':
-        ctx.push(
-          MapPage.route(
-            options: MapPageOptions(
-              initialLayers: {MapLayer.monitor},
-            ),
-          ),
-        );
+        MapRoute(layers: MapLayer.monitor.name).push(context);
         break;
     }
   }

lib/app/changelog/_widgets/update_card.dart

@@ -1,11 +1,26 @@
+/// A card widget that highlights an available app update.
+library;
+
 import 'package:dpip/utils/extensions/build_context.dart';
 import 'package:flutter/material.dart';
 
+/// Displays a summary card for an available update.
+///
+/// Shows [title], [description], and an optional [onViewDetails] callback.
+/// The card uses a gradient derived from the current theme's primary color.
 class UpdateCard extends StatelessWidget {
+  /// The update title (typically the version name).
   final String title;
+
+  /// A brief description of what changed in this update.
   final String description;
+
+  /// Called when the user taps to view full release details.
+  ///
+  /// When `null`, no interactive affordance is shown.
   final VoidCallback? onViewDetails;
 
+  /// Creates an [UpdateCard] with the given [title] and [description].
   const UpdateCard({
     super.key,
     required this.title,
@@ -17,27 +32,29 @@ class UpdateCard extends StatelessWidget {
   Widget build(BuildContext context) {
     return Card(
       elevation: 8,
-      shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(20)),
+      shape: RoundedRectangleBorder(
+        borderRadius: .circular(20),
+      ),
       child: Container(
         decoration: BoxDecoration(
-          borderRadius: BorderRadius.circular(20),
+          borderRadius: .circular(20),
           gradient: LinearGradient(
-            begin: Alignment.topLeft,
-            end: Alignment.bottomRight,
+            begin: .topLeft,
+            end: .bottomRight,
             colors: [
               context.theme.primaryColor.withValues(alpha: 0.1),
               context.theme.primaryColor.withValues(alpha: 0.3),
             ],
           ),
         ),
         child: Padding(
-          padding: const EdgeInsets.all(20.0),
+          padding: const .all(20),
           child: Row(
-            crossAxisAlignment: CrossAxisAlignment.start,
+            crossAxisAlignment: .start,
             children: [
               Expanded(
                 child: Column(
-                  crossAxisAlignment: CrossAxisAlignment.start,
+                  crossAxisAlignment: .start,
                   children: [
                     Row(
                       children: [
@@ -49,8 +66,8 @@ class UpdateCard extends StatelessWidget {
                         const SizedBox(width: 10),
                         Text(
                           title,
-                          style: context.theme.textTheme.titleLarge?.copyWith(
-                            fontWeight: FontWeight.bold,
+                          style: context.texts.titleLarge?.copyWith(
+                            fontWeight: .bold,
                             color: context.theme.primaryColor,
                           ),
                         ),
@@ -59,8 +76,8 @@ class UpdateCard extends StatelessWidget {
                     const SizedBox(height: 12),
                     Text(
                       description,
-                      style: context.theme.textTheme.bodyMedium?.copyWith(
-                        color: context.theme.textTheme.bodyMedium?.color
+                      style: context.texts.bodyMedium?.copyWith(
+                        color: context.texts.bodyMedium?.color
                             ?.withValues(alpha: 0.8),
                       ),
                     ),
@@ -73,9 +90,13 @@ class UpdateCard extends StatelessWidget {
                 height: 80,
                 decoration: BoxDecoration(
                   color: Colors.amber.withValues(alpha: 0.2),
-                  shape: BoxShape.circle,
+                  shape: .circle,
+                ),
+                child: const Icon(
+                  Icons.update,
+                  size: 48,
+                  color: Colors.amber,
                 ),
-                child: const Icon(Icons.update, size: 48, color: Colors.amber),
               ),
             ],
           ),

lib/app/changelog/page.dart

@@ -1,3 +1,6 @@
+/// The changelog page, displaying a list of GitHub releases for the app.
+library;
+
 import 'dart:async';
 
 import 'package:dpip/api/exptech.dart';
@@ -14,7 +17,12 @@ import 'package:m3e_collection/m3e_collection.dart';
 import 'package:material_symbols_icons/material_symbols_icons.dart';
 import 'package:option_result/result.dart';
 
+/// Displays the full release changelog fetched from GitHub.
+///
+/// Renders each [GithubRelease] with a sticky header and Markdown body.
+/// Pull-to-refresh triggers a fresh network fetch.
 class ChangelogPage extends StatefulWidget {
+  /// Creates a [ChangelogPage].
   const ChangelogPage({super.key});
 
   @override
@@ -23,6 +31,8 @@ class ChangelogPage extends StatefulWidget {
 
 class _ChangelogPageState extends State<ChangelogPage> {
   final _refreshIndicatorKey = GlobalKey<ExpressiveRefreshIndicatorState>();
+
+  /// The most recently fetched releases result, or `null` while loading.
   Result<List<GithubRelease>, String>? releases;
 
   Future<void> _refresh() async {
@@ -130,13 +140,17 @@ class _ChangelogPageState extends State<ChangelogPage> {
   }
 }
 
+/// A [SliverPersistentHeaderDelegate] that renders a sticky release header.
+///
+/// Shows the release icon, name, publish date, and a "current version" badge
+/// when the release matches the installed app version.
 class _ReleaseHeaderDelegate extends SliverPersistentHeaderDelegate {
+  /// The release whose metadata is shown in this header.
   final GithubRelease release;
 
+  /// Creates a [_ReleaseHeaderDelegate] for the given [release].
   const _ReleaseHeaderDelegate(this.release);
 
-  static const height = kToolbarHeight + 32;
-
   @override
   double get minExtent => height;
 
@@ -209,4 +223,7 @@ class _ReleaseHeaderDelegate extends SliverPersistentHeaderDelegate {
 
   @override
   bool shouldRebuild(covariant _ReleaseHeaderDelegate oldDelegate) => true;
+
+  /// Fixed height of the header in logical pixels.
+  static const height = kToolbarHeight + 32;
 }

lib/app/debug/logs/page.dart

@@ -1,14 +1,20 @@
+/// The debug logs page, displaying in-app Talker log output.
+library;
+
 import 'package:dpip/core/i18n.dart';
 import 'package:dpip/utils/extensions/build_context.dart';
 import 'package:dpip/utils/log.dart';
 import 'package:flutter/material.dart';
 import 'package:talker_flutter/talker_flutter.dart';
 
+/// Renders the full Talker log screen for in-app debugging.
+///
+/// Theming is derived from the current [BuildContext] color scheme so the
+/// screen respects light/dark mode automatically.
 class AppDebugLogsPage extends StatelessWidget {
+  /// Creates an [AppDebugLogsPage].
   const AppDebugLogsPage({super.key});
 
-  static const route = '/debug/logs';
-
   @override
   Widget build(BuildContext context) {
     return TalkerScreen(

lib/app/home/_models/home_location.dart

@@ -1,10 +1,22 @@
+/// Model for temporarily overriding the home screen location.
+library;
+
 import 'package:flutter/material.dart';
 
+/// Holds an optional temporary location code for the home screen.
+///
+/// When [temporaryCode] is non-null, the home page uses it instead of the
+/// user's persisted location setting. Call [setTemporaryCode] to update and
+/// notify listeners.
 class HomeLocationModel extends ChangeNotifier {
   String? _temporaryCode;
 
+  /// The current temporary location code, or `null` when none is set.
   String? get temporaryCode => _temporaryCode;
 
+  /// Updates [temporaryCode] to [code] and notifies listeners.
+  ///
+  /// Does nothing if [code] equals the current value.
   void setTemporaryCode(String? code) {
     if (_temporaryCode == code) return;
     _temporaryCode = code;