From 16566e5e635281e5ac28425ca71bb63056154878 Mon Sep 17 00:00:00 2001 From: Merack Date: Sat, 30 May 2026 12:52:28 +0800 Subject: [PATCH 1/5] feat: custom ringtone --- .agents/skills/dart-add-unit-test/SKILL.md | 122 +++++++ .agents/skills/dart-build-cli-app/SKILL.md | 185 +++++++++++ .agents/skills/dart-collect-coverage/SKILL.md | 141 ++++++++ .../skills/dart-fix-runtime-errors/SKILL.md | 166 ++++++++++ .../skills/dart-generate-test-mocks/SKILL.md | 155 +++++++++ .../dart-migrate-to-checks-package/SKILL.md | 118 +++++++ .../dart-resolve-package-conflicts/SKILL.md | 116 +++++++ .../skills/dart-run-static-analysis/SKILL.md | 104 ++++++ .../skills/dart-use-pattern-matching/SKILL.md | 146 +++++++++ .../flutter-add-integration-test/SKILL.md | 163 ++++++++++ .../flutter-add-widget-preview/SKILL.md | 145 +++++++++ .../skills/flutter-add-widget-test/SKILL.md | 154 +++++++++ .../SKILL.md | 162 ++++++++++ .../flutter-build-responsive-layout/SKILL.md | 139 ++++++++ .../skills/flutter-fix-layout-issues/SKILL.md | 130 ++++++++ .../SKILL.md | 153 +++++++++ .../SKILL.md | 255 +++++++++++++++ .../flutter-setup-localization/SKILL.md | 210 ++++++++++++ .../skills/flutter-use-http-package/SKILL.md | 174 ++++++++++ .gitignore | 3 +- android/app/build.gradle.kts | 16 +- android/app/src/main/AndroidManifest.xml | 8 +- .../top/merack/time_machine/MainActivity.kt | 22 +- .../merack/time_machine/RingtoneChannel.kt | 300 ++++++++++++++++++ android/gradle.properties | 7 + .../gradle/wrapper/gradle-wrapper.properties | 2 +- android/settings.gradle.kts | 4 +- lib/config/storage_keys.dart | 51 +++ lib/database/backup_restore_db_service.dart | 8 +- lib/main.dart | 42 ++- lib/page/home/controller.dart | 75 ++++- lib/page/setting/controller.dart | 28 ++ lib/page/setting/view.dart | 26 ++ .../setting/widgets/permission_settings.dart | 157 +++++++++ .../setting/widgets/pomodoro_settings.dart | 1 - lib/page/setting/widgets/setting_tile.dart | 12 +- lib/page/setting/widgets/widgets.dart | 1 + lib/page/sound_settings/controller.dart | 249 +++++++++++++++ lib/page/sound_settings/state.dart | 29 ++ lib/page/sound_settings/view.dart | 88 +++++ .../widgets/sound_picker_dialog.dart | 217 +++++++++++++ lib/route/route_name.dart | 1 + lib/route/route_page.dart | 2 + lib/service/custom_sound_storage_service.dart | 140 ++++++++ lib/service/permission_service.dart | 102 ++++++ lib/service/ringtone_picker_service.dart | 93 ++++++ pubspec.lock | 60 +++- pubspec.yaml | 1 + skills-lock.json | 119 +++++++ .../flutter/generated_plugin_registrant.cc | 3 + windows/flutter/generated_plugins.cmake | 1 + 51 files changed, 4769 insertions(+), 37 deletions(-) create mode 100644 .agents/skills/dart-add-unit-test/SKILL.md create mode 100644 .agents/skills/dart-build-cli-app/SKILL.md create mode 100644 .agents/skills/dart-collect-coverage/SKILL.md create mode 100644 .agents/skills/dart-fix-runtime-errors/SKILL.md create mode 100644 .agents/skills/dart-generate-test-mocks/SKILL.md create mode 100644 .agents/skills/dart-migrate-to-checks-package/SKILL.md create mode 100644 .agents/skills/dart-resolve-package-conflicts/SKILL.md create mode 100644 .agents/skills/dart-run-static-analysis/SKILL.md create mode 100644 .agents/skills/dart-use-pattern-matching/SKILL.md create mode 100644 .agents/skills/flutter-add-integration-test/SKILL.md create mode 100644 .agents/skills/flutter-add-widget-preview/SKILL.md create mode 100644 .agents/skills/flutter-add-widget-test/SKILL.md create mode 100644 .agents/skills/flutter-apply-architecture-best-practices/SKILL.md create mode 100644 .agents/skills/flutter-build-responsive-layout/SKILL.md create mode 100644 .agents/skills/flutter-fix-layout-issues/SKILL.md create mode 100644 .agents/skills/flutter-implement-json-serialization/SKILL.md create mode 100644 .agents/skills/flutter-setup-declarative-routing/SKILL.md create mode 100644 .agents/skills/flutter-setup-localization/SKILL.md create mode 100644 .agents/skills/flutter-use-http-package/SKILL.md create mode 100644 android/app/src/main/kotlin/top/merack/time_machine/RingtoneChannel.kt create mode 100644 lib/page/setting/widgets/permission_settings.dart create mode 100644 lib/page/sound_settings/controller.dart create mode 100644 lib/page/sound_settings/state.dart create mode 100644 lib/page/sound_settings/view.dart create mode 100644 lib/page/sound_settings/widgets/sound_picker_dialog.dart create mode 100644 lib/service/custom_sound_storage_service.dart create mode 100644 lib/service/permission_service.dart create mode 100644 lib/service/ringtone_picker_service.dart create mode 100644 skills-lock.json diff --git a/.agents/skills/dart-add-unit-test/SKILL.md b/.agents/skills/dart-add-unit-test/SKILL.md new file mode 100644 index 0000000..dc27083 --- /dev/null +++ b/.agents/skills/dart-add-unit-test/SKILL.md @@ -0,0 +1,122 @@ +--- +name: dart-add-unit-test +description: Write and organize unit tests for functions, methods, and classes using `package:test`. Use when creating new logic or fixing bugs to ensure code remains correct and regression-free. +metadata: + model: models/gemini-3.1-pro-preview + last_modified: Fri, 24 Apr 2026 15:07:58 GMT +--- +# Testing Dart and Flutter Applications + +## Contents +- [Structuring Test Files](#structuring-test-files) +- [Writing Tests](#writing-tests) +- [Executing Tests](#executing-tests) +- [Test Implementation Workflow](#test-implementation-workflow) +- [Examples](#examples) + +## Structuring Test Files +Organize test files to mirror the `lib` directory structure to maintain predictability. + +* Place all test code within the `test` directory at the root of the package. +* Append `_test.dart` to the end of all test file names (e.g., `lib/src/utils.dart` should be tested in `test/src/utils_test.dart`). +* If writing integration tests, place them in an `integration_test` directory at the root of the package. + +## Writing Tests +Utilize `package:test` as the standard testing library for Dart applications. + +* Import `package:test/test.dart` (or `package:flutter_test/flutter_test.dart` for Flutter). +* Group related tests using the `group()` function to provide shared context. +* Define individual test cases using the `test()` function. +* Validate outcomes using the `expect()` function alongside matchers (e.g., `equals()`, `isTrue`, `throwsA()`). +* Write asynchronous tests using standard `async`/`await` syntax. The test runner automatically waits for the `Future` to complete. +* Manage test setup and teardown using `setUp()` and `tearDown()` callbacks. +* If testing code that relies on dependency injection, use `package:mockito` alongside `package:test` to generate mock objects, configure fixed scenarios, and verify interactions. + +## Executing Tests +Select the appropriate test runner based on the project type and test location. + +* If working on a pure Dart project, execute tests using the `dart test` command. +* If working on a Flutter project, execute tests using the `flutter test` command. +* If running integration tests, explicitly specify the directory path, as the default runner ignores it: `dart test integration_test` or `flutter test integration_test`. + +## Test Implementation Workflow + +Follow this sequential workflow when implementing new test suites. Copy the checklist to track your progress. + +### Task Progress +- [ ] 1. Create the test file in the `test/` directory, ensuring the `_test.dart` suffix. +- [ ] 2. Import `package:test/test.dart` and the target library. +- [ ] 3. Define a `main()` function. +- [ ] 4. Initialize shared resources or mocks using `setUp()`. +- [ ] 5. Write `test()` cases grouped by functionality using `group()`. +- [ ] 6. Execute the test suite using the appropriate CLI command. +- [ ] 7. **Feedback Loop**: Run test -> Review stack trace for failures -> Fix implementation or assertions -> Re-run until passing. + +## Examples + +### Standard Unit Test Suite +Demonstrates grouping, setup, synchronous, and asynchronous testing. + +```dart +import 'package:test/test.dart'; +import 'package:my_package/calculator.dart'; + +void main() { + group('Calculator', () { + late Calculator calc; + + setUp(() { + calc = Calculator(); + }); + + test('adds two numbers correctly', () { + expect(calc.add(2, 3), equals(5)); + }); + + test('handles asynchronous operations', () async { + final result = await calc.fetchRemoteValue(); + expect(result, isNotNull); + expect(result, greaterThan(0)); + }); + }); +} +``` + +### Mocking with Mockito +Demonstrates configuring a mock object for dependency injection testing. + +```dart +import 'package:test/test.dart'; +import 'package:mockito/mockito.dart'; +import 'package:mockito/annotations.dart'; +import 'package:my_package/api_client.dart'; +import 'package:my_package/data_service.dart'; + +// Generate the mock using build_runner: dart run build_runner build +@GenerateNiceMocks([MockSpec()]) +import 'data_service_test.mocks.dart'; + +void main() { + group('DataService', () { + late MockApiClient mockApiClient; + late DataService dataService; + + setUp(() { + mockApiClient = MockApiClient(); + dataService = DataService(apiClient: mockApiClient); + }); + + test('returns parsed data on successful API call', () async { + // Configure the mock + when(mockApiClient.get('/data')).thenAnswer((_) async => '{"id": 1}'); + + // Execute the system under test + final result = await dataService.fetchData(); + + // Verify outcomes and interactions + expect(result.id, equals(1)); + verify(mockApiClient.get('/data')).called(1); + }); + }); +} +``` diff --git a/.agents/skills/dart-build-cli-app/SKILL.md b/.agents/skills/dart-build-cli-app/SKILL.md new file mode 100644 index 0000000..239a892 --- /dev/null +++ b/.agents/skills/dart-build-cli-app/SKILL.md @@ -0,0 +1,185 @@ +--- +name: dart-build-cli-app +description: Entrypoint structure, exit codes, cross-platform scripts. Use when building command line utilities, scripts, or applications. +metadata: + model: models/gemini-3.1-pro-preview + last_modified: Fri, 04 May 2026 17:41:00 GMT +--- +# Building Dart CLI Applications + +## Contents +- [Project Setup & Architecture](#project-setup--architecture) +- [Argument Parsing & Command Routing](#argument-parsing--command-routing) +- [Execution & Error Handling](#execution--error-handling) +- [Testing CLI Applications](#testing-cli-applications) +- [Compilation & Distribution](#compilation--distribution) +- [Workflows](#workflows) +- [Examples](#examples) + +## Project Setup & Architecture + +Initialize new CLI projects using the official Dart template to ensure standard directory structures. + +* Run `dart create -t cli ` to scaffold a console application with basic argument parsing. +* Place executable entry points (files containing `main()`) exclusively in the `bin/` directory. +* Place internal implementation logic in `lib/src/` and expose public APIs via `lib/.dart`. +* Enforce formatting in CI environments by running `dart format . --set-exit-if-changed`. This returns exit code 1 if formatting violations exist. + +## Argument Parsing & Command Routing + +Import the `args` package to manage command-line arguments, flags, and subcommands. + +* If building a simple script: Use `ArgParser` directly to define flags (`addFlag`) and options (`addOption`). +* If building a complex, multi-command CLI (like `git`): Implement `CommandRunner` and extend `Command` for each subcommand. +* Define global arguments on the `CommandRunner.argParser` and command-specific arguments on the individual `Command.argParser`. +* Catch `UsageException` to gracefully handle invalid arguments and display the automatically generated help text. +* **Validate Help Text Accuracy**: Ensure the help text provides all necessary information to run the tool. If the help text references a compiled executable name, and the user needs to add it to their PATH to run it that way, provide clear instructions on how to do so in the help text or description. + +## Execution & Error Handling + +Leverage the `io` and `stack_trace` packages to build robust, production-ready CLI tools. + +* Use the `io` package's `ExitCode` enum to return standard POSIX exit codes (e.g., `ExitCode.success.code`, `ExitCode.usage.code`). +* Use `sharedStdIn` from the `io` package if multiple asynchronous listeners need sequential access to standard input. +* Wrap the application execution in `Chain.capture()` from the `stack_trace` package to track asynchronous stack chains. +* Format output stack traces using `Trace.terse` or `Chain.terse` to strip noisy core library frames and present readable errors to the user. +* **Do not swallow exceptions** in lower-level logic or storage classes unless recovery is possible. Let them bubble up or rethrow them so higher-level commands know operations failed. +* **Fail fast and with non-zero exit codes**: Ensure operation failures result in descriptive error messages to `stderr` and appropriate non-zero exit codes (e.g., using `exit(1)` or triggering a 64 exit code after a caught `UsageException`). + +## Testing CLI Applications + +> [!IMPORTANT] +> **All new commands and significant features must be covered by automated tests.** Manual verification is not sufficient for testing logic. However, manual verification of help text and user experience (UX) is still required to ensure the interface is intuitive and correct. + +Use `test_process` and `test_descriptor` to write high-fidelity integration tests for your CLI. + +* Define expected filesystem states using `test_descriptor` (`d.dir`, `d.file`). +* Create the mock filesystem before execution using `await d.Descriptor.create()`. +* Spawn the CLI process using `TestProcess.start('dart', ['run', 'bin/cli.dart', ...args])`. +* Validate standard output and error streams using `StreamQueue` matchers (e.g., `emitsThrough`, `emits`). +* Assert the final exit code using `await process.shouldExit(0)`. +* Validate resulting filesystem mutations using `await d.Descriptor.validate()`. + +## Compilation & Distribution + +Select the appropriate compilation target based on your distribution requirements. + +* **If testing locally during development:** Use `dart run bin/cli.dart`. This uses the JIT compiler for rapid iteration. +* **If bundling code assets and dynamic libraries:** Use `dart build cli`. This runs build hooks and outputs to `build/cli/_/bundle/`. +* **If distributing a standalone native executable:** Use `dart compile exe bin/cli.dart -o `. This bundles the Dart runtime and machine code into a single file. +* **If distributing multiple apps with strict disk space limits:** Use `dart compile aot-snapshot bin/cli.dart`. Run the resulting `.aot` file using `dartaotruntime`. + +
+Cross-Compilation Targets (Linux Only) + +Dart supports cross-compiling to Linux from macOS, Windows, or Linux hosts. +Use the `--target-os` and `--target-arch` flags with `dart compile exe` or `dart compile aot-snapshot`. + +* `--target-os=linux` (Only Linux is currently supported as a cross-compilation target) +* `--target-arch=arm64` (64-bit ARM) +* `--target-arch=x64` (x86-64) +* `--target-arch=arm` (32-bit ARM) +* `--target-arch=riscv64` (64-bit RISC-V) + +Example: `dart compile exe --target-os=linux --target-arch=arm64 bin/cli.dart` +
+ +## Workflows + +### Task Progress: Implement a New CLI Command +- [ ] Create a new class extending `Command` in `lib/src/commands/`. +- [ ] Define the `name` and `description` properties. +- [ ] Register command-specific flags in the constructor using `argParser.addFlag()` or `argParser.addOption()`. +- [ ] Implement the `run()` method with the core logic. +- [ ] Register the new command in the `CommandRunner` instance in `bin/cli.dart` using `addCommand()`. +- [ ] Create tests for the new command in the `test/` directory using `test_process` or standard tests. +- [ ] Run validator -> Execute `dart run bin/cli.dart help ` to verify help text generation. +- [ ] Verify final UX: Compile the application using `dart compile exe` and run the resulting executable to verify the target user experience (e.g., `./bin/cli `). + +### Task Progress: Compile and Release Native Executable +- [ ] Run validator -> Execute `dart format . --set-exit-if-changed` to ensure code formatting. +- [ ] Run validator -> Execute `dart analyze` to ensure no static analysis errors. +- [ ] Run validator -> Execute `dart test` to pass all integration tests. +- [ ] Compile for host OS: `dart compile exe bin/cli.dart -o build/cli-host` +- [ ] Compile for Linux (if host is macOS/Windows): `dart compile exe --target-os=linux --target-arch=x64 bin/cli.dart -o build/cli-linux-x64` + +## Examples + +### Example: CommandRunner Implementation + +```dart +import 'dart:io'; +import 'package:args/command_runner.dart'; +import 'package:stack_trace/stack_trace.dart'; + +class CommitCommand extends Command { + @override + final String name = 'commit'; + @override + final String description = 'Record changes to the repository.'; + + CommitCommand() { + argParser.addFlag('all', abbr: 'a', help: 'Commit all changed files.'); + } + + @override + Future run() async { + final commitAll = argResults?['all'] as bool? ?? false; + print('Committing... (All: $commitAll)'); + } +} + +void main(List args) { + Chain.capture(() async { + final runner = CommandRunner('dgit', 'Distributed version control.') + ..addCommand(CommitCommand()); + + await runner.run(args); + }, onError: (error, chain) { + if (error is UsageException) { + stderr.writeln(error.message); + stderr.writeln(error.usage); + exit(64); // ExitCode.usage.code + } else { + stderr.writeln('Fatal error: $error'); + stderr.writeln(chain.terse); + exit(1); + } + }); +} +``` + +### Example: Integration Testing with Subprocesses + +```dart +import 'package:test/test.dart'; +import 'package:test_process/test_process.dart'; +import 'package:test_descriptor/test_descriptor.dart' as d; + +void main() { + test('CLI formats output correctly and modifies filesystem', () async { + // 1. Setup mock filesystem + await d.dir('project', [ + d.file('config.json', '{"key": "value"}') + ]).create(); + + // 2. Spawn the CLI process + final process = await TestProcess.start( + 'dart', + ['run', 'bin/cli.dart', 'process', '--path', '${d.sandbox}/project'] + ); + + // 3. Validate stdout stream + await expectLater(process.stdout, emitsThrough('Processing complete.')); + + // 4. Validate exit code + await process.shouldExit(0); + + // 5. Validate filesystem mutations + await d.dir('project', [ + d.file('config.json', '{"key": "value"}'), + d.file('output.log', 'Success') + ]).validate(); + }); +} +``` diff --git a/.agents/skills/dart-collect-coverage/SKILL.md b/.agents/skills/dart-collect-coverage/SKILL.md new file mode 100644 index 0000000..60dad77 --- /dev/null +++ b/.agents/skills/dart-collect-coverage/SKILL.md @@ -0,0 +1,141 @@ +--- +name: dart-collect-coverage +description: Collect coverage using the coverage packge and create an LCOV report +metadata: + model: models/gemini-3.1-pro-preview + last_modified: Fri, 24 Apr 2026 15:14:32 GMT +--- +# Implementing Dart and Flutter Test Coverage + +## Contents +- [Testing Fundamentals](#testing-fundamentals) +- [Coverage Directives](#coverage-directives) +- [Workflow: Configuring and Generating Coverage Reports](#workflow-configuring-and-generating-coverage-reports) +- [Workflow: Advanced Manual Coverage Collection](#workflow-advanced-manual-coverage-collection) +- [Examples](#examples) + +## Testing Fundamentals + +Structure your test suites using the standard Dart testing paradigms. Use `package:test` for Dart projects and `flutter_test` for Flutter projects. + +- **Unit Tests:** Verify individual functions, methods, or classes. +- **Component/Widget Tests:** Verify component behavior, layout, and interaction using mock objects (`package:mockito`). +- **Integration Tests:** Verify entire app flows on simulated or real devices. + +## Coverage Directives + +Exclude specific lines, blocks, or entire files from coverage metrics using inline comments. Pass the `--check-ignore` flag during formatting to enforce these directives. + +- Ignore a single line: `// coverage:ignore-line` +- Ignore a block of code: `// coverage:ignore-start` and `// coverage:ignore-end` +- Ignore an entire file: `// coverage:ignore-file` + +## Workflow: Configuring and Generating Coverage Reports + +Follow this sequential workflow to add the coverage package, execute tests, and generate an LCOV report. + +**Task Progress Checklist:** +- [ ] 1. Add `coverage` as a `dev_dependency`. +- [ ] 2. Execute the automated coverage script. +- [ ] 3. Validate the LCOV output. + +### 1. Add Dependencies +Add the `coverage` package as a `dev_dependency` to your project. Do not add it to standard dependencies. + +If working in a standard Dart project: +```bash +dart pub add dev:coverage +``` + +If working in a Flutter project: +```bash +flutter pub add dev:coverage +``` + +### 2. Collect Coverage and Generate LCOV +Use the bundled `test_with_coverage` script. This script automatically runs all tests, collects the JSON coverage data from the Dart VM, and formats it into an LCOV report. + +```bash +dart run coverage:test_with_coverage +``` +*Note: If working within a Dart workspace (monorepo), specify the test directories explicitly (e.g., `dart run coverage:test_with_coverage -- pkgs/foo/test pkgs/bar/test`).* + +### 3. Feedback Loop: Validate Output +**Run validator -> review errors -> fix:** +1. Verify that the `coverage/` directory was created in the project root. +2. Ensure `coverage/coverage.json` (raw data) and `coverage/lcov.info` (formatted report) exist. +3. If coverage is missing for specific files, ensure they are imported and executed by your test files, or add `// coverage:ignore-file` if they are intentionally excluded. + +## Workflow: Advanced Manual Coverage Collection + +If you require granular control over the VM service, isolate pausing, or need branch/function-level coverage, use the manual collection workflow. + +**Task Progress Checklist:** +- [ ] 1. Run tests with VM service enabled. +- [ ] 2. Collect raw JSON coverage. +- [ ] 3. Format JSON to LCOV. + +### 1. Run Tests with VM Service +Execute tests while pausing isolates on exit and exposing the VM service on a specific port (e.g., 8181). + +```bash +dart run --pause-isolates-on-exit --disable-service-auth-codes --enable-vm-service=8181 test & +``` + +### 2. Collect Raw Coverage +Extract the coverage data from the running VM service and output it to a JSON file. + +```bash +dart run coverage:collect_coverage --wait-paused --uri=http://127.0.0.1:8181/ -o coverage/coverage.json --resume-isolates +``` +*Optional: Append `--function-coverage` and `--branch-coverage` to gather deeper metrics (requires Dart VM 2.17.0+).* + +### 3. Format to LCOV +Convert the raw JSON data into the standard LCOV format. + +```bash +dart run coverage:format_coverage --packages=.dart_tool/package_config.json --lcov -i coverage/coverage.json -o coverage/lcov.info --check-ignore +``` + +## Examples + +### Example: `pubspec.yaml` Configuration +Ensure your `pubspec.yaml` reflects the `coverage` package strictly under `dev_dependencies`. + +```yaml +name: my_dart_app +environment: + sdk: ^3.0.0 + +dependencies: + path: ^1.8.0 + +dev_dependencies: + test: ^1.24.0 + coverage: ^1.15.0 +``` + +### Example: Applying Ignore Directives +Use ignore directives to prevent generated code or untestable edge cases from lowering coverage scores. + +```dart +// coverage:ignore-file +import 'package:meta/meta.dart'; + +class SystemConfig { + final String env; + + SystemConfig(this.env); + + // coverage:ignore-start + void legacyInit() { + print('Deprecated initialization'); + } + // coverage:ignore-end + + bool isProduction() { + if (env == 'prod') return true; + return false; // coverage:ignore-line + } +} +``` diff --git a/.agents/skills/dart-fix-runtime-errors/SKILL.md b/.agents/skills/dart-fix-runtime-errors/SKILL.md new file mode 100644 index 0000000..1a7db85 --- /dev/null +++ b/.agents/skills/dart-fix-runtime-errors/SKILL.md @@ -0,0 +1,166 @@ +--- +name: dart-fix-runtime-errors +description: Uses get_runtime_errors and lsp to fetch an active stack trace, locate the failing line, apply a fix, and verify resolution via hot_reload. +metadata: + model: models/gemini-3.1-pro-preview + last_modified: Fri, 24 Apr 2026 15:13:22 GMT +--- +# Resolving Dart Static Analysis Errors + +## Contents +- [Core Concepts & Guidelines](#core-concepts--guidelines) + - [Type System & Soundness](#type-system--soundness) + - [Null Safety](#null-safety) + - [Error Handling](#error-handling) +- [Workflows](#workflows) + - [Workflow: Static Analysis Resolution](#workflow-static-analysis-resolution) +- [Examples](#examples) + +## Core Concepts & Guidelines + +### Type System & Soundness +Enforce Dart's sound type system to prevent runtime invalid states. + +* **Method Overrides:** Maintain sound return types (covariant) and parameter types (contravariant). Never tighten a parameter type in a subclass unless explicitly marked with the `covariant` keyword. +* **Generics & Collections:** Add explicit type annotations to generic classes (e.g., `List`, `Map`). Never assign a `List` to a typed list (e.g., `List`). +* **Downcasting:** Avoid implicit downcasts from `dynamic`. Use explicit casts (e.g., `as List`) when necessary, but ensure the underlying runtime type matches to prevent `TypeError` exceptions. +* **Strict Casts:** Enable `strict-casts: true` in `analysis_options.yaml` under `analyzer: language:` to force explicit casting and catch implicit downcast errors at compile time. + +### Null Safety +Eliminate static errors related to null safety by correctly managing variable initialization and nullability. + +* **Modifiers:** Apply `?` for nullable types, `!` for null assertions, and `required` for named parameters that cannot be null. +* **Late Initialization:** Use the `late` keyword for non-nullable variables guaranteed to be initialized before use. Apply this specifically to top-level or instance variables where Dart's control flow analysis cannot definitively prove initialization. +* **Wildcards:** Use the `_` wildcard variable (Dart 3.7+) for non-binding local variables or parameters to avoid unused variable warnings. + +### Error Handling +Distinguish between recoverable exceptions and unrecoverable errors. + +* **Catching:** Catch `Exception` subtypes for recoverable failures. +* **Errors:** Never explicitly catch `Error` or its subtypes (e.g., `TypeError`, `ArgumentError`). Errors indicate programming bugs that must be fixed, not caught. Enforce this by enabling the `avoid_catching_errors` linter rule. +* **Rethrowing:** Use `rethrow` inside a `catch` block to propagate an exception while preserving its original stack trace. + +## Workflows + +### Workflow: Static Analysis Resolution + +Use this sequential workflow to identify, fix, and verify static analysis errors in a Dart project. Copy the checklist to track your progress. + +**Task Progress:** +- [ ] 1. Run static analyzer. +- [ ] 2. Apply automated fixes. +- [ ] 3. Resolve remaining errors manually. +- [ ] 4. Verify fixes (Feedback Loop). + +**1. Run static analyzer** +Execute the Dart analyzer to identify all static errors in the target directory or file. +```bash +dart analyze . --fatal-infos +``` + +**2. Apply automated fixes** +Use the `dart fix` tool to automatically resolve standard linting and analysis issues. +```bash +# Preview changes +dart fix --dry-run +# Apply changes +dart fix --apply +``` + +**3. Resolve remaining errors manually** +Review the remaining analyzer output and apply conditional logic based on the error type: + +* **If the error is a Null Safety issue (e.g., "Property cannot be accessed on a nullable receiver"):** + * Verify if the variable can logically be null. + * If yes, use optional chaining (`?.`) or provide a fallback (`??`). + * If no, and initialization is guaranteed elsewhere, mark the declaration with `late`. +* **If the error is a Type Mismatch (e.g., "The argument type 'List' can't be assigned..."):** + * Trace the variable's initialization. + * Add explicit generic type annotations to the instantiation (e.g., `[]` instead of `[]`). +* **If the error is an Invalid Override (e.g., "The parameter type doesn't match the overridden method"):** + * Widen the parameter type to match the superclass, OR + * Add the `covariant` keyword to the parameter if tightening the type is intentionally required by the domain logic. + +**4. Verify fixes (Feedback Loop)** +Run the validator. Review errors. Fix. +```bash +dart analyze . +dart test +``` +* **If `dart analyze` reports errors:** Return to Step 3. +* **If `dart test` fails with a `TypeError`:** You have introduced an invalid explicit cast (`as T`) or accessed an uninitialized `late` variable. Locate the runtime failure and correct the type hierarchy or initialization order. + +## Examples + +### Example: Fixing Dynamic List Assignments +**Input (Fails Static Analysis):** +```dart +void printInts(List a) => print(a); + +void main() { + final list = []; // Inferred as List + list.add(1); + list.add(2); + printInts(list); // Error: List can't be assigned to List +} +``` + +**Output (Passes Static Analysis):** +```dart +void printInts(List a) => print(a); + +void main() { + final list = []; // Explicitly typed + list.add(1); + list.add(2); + printInts(list); +} +``` + +### Example: Fixing Method Overrides (Contravariance) +**Input (Fails Static Analysis):** +```dart +class Animal { + void chase(Animal a) {} +} + +class Cat extends Animal { + @override + void chase(Mouse a) {} // Error: Tightening parameter type +} +``` + +**Output (Passes Static Analysis):** +```dart +class Animal { + void chase(Animal a) {} +} + +class Cat extends Animal { + @override + void chase(covariant Mouse a) {} // Explicitly marked covariant +} +``` + +### Example: Fixing Null Safety with `late` +**Input (Fails Static Analysis):** +```dart +class Thermometer { + String temperature; // Error: Non-nullable instance field must be initialized + + void read() { + temperature = '20C'; + } +} +``` + +**Output (Passes Static Analysis):** +```dart +class Thermometer { + late String temperature; // Defers initialization check to runtime + + void read() { + temperature = '20C'; + } +} +``` diff --git a/.agents/skills/dart-generate-test-mocks/SKILL.md b/.agents/skills/dart-generate-test-mocks/SKILL.md new file mode 100644 index 0000000..fcd6d8b --- /dev/null +++ b/.agents/skills/dart-generate-test-mocks/SKILL.md @@ -0,0 +1,155 @@ +--- +name: dart-generate-test-mocks +description: Define and generate mock objects for external dependencies using `package:mockito` and `build_runner`. Use when unit testing classes that depend on complex external services like APIs or databases. +metadata: + model: models/gemini-3.1-pro-preview + last_modified: Fri, 24 Apr 2026 15:13:58 GMT +--- +# Testing and Mocking Dart Applications + +## Contents +- [Structuring Code for Testability](#structuring-code-for-testability) +- [Managing Dependencies](#managing-dependencies) +- [Generating Mocks](#generating-mocks) +- [Implementing Unit Tests](#implementing-unit-tests) +- [Workflow: Creating and Running Mocked Tests](#workflow-creating-and-running-mocked-tests) +- [Examples](#examples) + +## Structuring Code for Testability +Design Dart classes to support dependency injection. Isolate complex external dependencies (like API clients or databases) so they can be replaced with mock objects during testing. + +- Inject external services (e.g., `http.Client`) through class constructors. +- Represent URLs strictly as `Uri` objects using `Uri.parse(string)`. +- Utilize Dart's object-oriented features (classes, mixins) to define clear interfaces for external interactions. + +## Managing Dependencies +Configure the `pubspec.yaml` file with the necessary testing and code generation packages. + +- Add runtime dependencies (e.g., `package:http`) using `dart pub add http`. +- Add testing dependencies using `dart pub add dev:test dev:mockito dev:build_runner`. +- Import HTTP libraries with a prefix to avoid namespace collisions: `import 'package:http/http.dart' as http;`. + +## Generating Mocks +Use `package:mockito` and `build_runner` to automatically generate mock classes for fixed scenarios and behavior verification. + +- Always use the `@GenerateNiceMocks` annotation (preferable to `@GenerateMocks` to avoid missing stub exceptions). +- Place the annotation in the test file, passing a list of `MockSpec()` objects. +- Import the generated file using the `.mocks.dart` extension. +- Execute `build_runner` to generate the mock files: `dart run build_runner build`. + +## Implementing Unit Tests +Isolate the system under test using the generated mock objects. Use `package:test` to structure the test suite. + +- **Stubbing:** Configure mock behavior before interacting with the system under test. + - Use `when(mock.method()).thenReturn(value)` for synchronous methods. + - **CRITICAL:** Always use `thenAnswer((_) async => value)` for methods returning a `Future` or `Stream`. Never use `thenReturn` for asynchronous returns. +- **Verification:** Assert that the system under test interacted with the mock object correctly. + - Use `verify(mock.method()).called(1)` to check exact invocation counts. + - Use argument matchers like `any`, `anyNamed`, or `captureAny` for flexible verification. + +## Workflow: Creating and Running Mocked Tests + +Use the following checklist to implement and verify mocked unit tests. + +### Task Progress +- [ ] 1. Identify the external dependency to mock (e.g., `http.Client`). +- [ ] 2. Inject the dependency into the target class constructor. +- [ ] 3. Create a test file (e.g., `target_test.dart`) and add `@GenerateNiceMocks([MockSpec()])`. +- [ ] 4. Add the `part` or `import` directive for the generated `.mocks.dart` file. +- [ ] 5. Run `dart run build_runner build` to generate the mock classes. +- [ ] 6. Write the test cases using `group()` and `test()`. +- [ ] 7. Stub required behaviors using `when()`. +- [ ] 8. Execute the target method. +- [ ] 9. Verify interactions using `verify()` and assert outcomes using `expect()`. +- [ ] 10. Run the test suite using `dart test`. + +### Feedback Loop: Test Failures +If tests fail or `build_runner` encounters errors: +1. **Run validator:** Execute `dart test` or `dart run build_runner build`. +2. **Review errors:** Check for missing stubs, mismatched argument matchers, or syntax errors in the generated files. +3. **Fix:** + - If a mock method throws an unexpected null error, ensure you used `@GenerateNiceMocks`. + - If an async stub throws an `ArgumentError`, change `thenReturn` to `thenAnswer`. + - If `build_runner` fails, ensure the `.mocks.dart` import matches the file name exactly. +4. Repeat until all tests pass. + +## Examples + +### High-Fidelity Mocking and Testing Example + +**1. System Under Test (`lib/api_service.dart`)** +```dart +import 'dart:convert'; +import 'package:http/http.dart' as http; + +class ApiService { + final http.Client client; + + ApiService(this.client); + + Future fetchData(String urlString) async { + final uri = Uri.parse(urlString); + final response = await client.get(uri); + + if (response.statusCode == 200) { + return jsonDecode(response.body)['data']; + } else { + throw Exception('Failed to load data'); + } + } +} +``` + +**2. Test Implementation (`test/api_service_test.dart`)** +```dart +import 'package:test/test.dart'; +import 'package:mockito/annotations.dart'; +import 'package:mockito/mockito.dart'; +import 'package:http/http.dart' as http; +import 'package:my_app/api_service.dart'; + +// Generate the mock class for http.Client +@GenerateNiceMocks([MockSpec()]) +import 'api_service_test.mocks.dart'; + +void main() { + group('ApiService', () { + late ApiService apiService; + late MockClient mockHttpClient; + + setUp(() { + mockHttpClient = MockClient(); + apiService = ApiService(mockHttpClient); + }); + + test('returns data if the http call completes successfully', () async { + // Arrange: Stub the async HTTP GET request using thenAnswer + when(mockHttpClient.get(any)).thenAnswer( + (_) async => http.Response('{"data": "Success"}', 200), + ); + + // Act + final result = await apiService.fetchData('https://api.example.com/data'); + + // Assert + expect(result, 'Success'); + + // Verify the mock was called with the correct Uri + verify(mockHttpClient.get(Uri.parse('https://api.example.com/data'))).called(1); + }); + + test('throws an exception if the http call completes with an error', () { + // Arrange + when(mockHttpClient.get(any)).thenAnswer( + (_) async => http.Response('Not Found', 404), + ); + + // Act & Assert + expect( + apiService.fetchData('https://api.example.com/data'), + throwsException, + ); + }); + }); +} +``` diff --git a/.agents/skills/dart-migrate-to-checks-package/SKILL.md b/.agents/skills/dart-migrate-to-checks-package/SKILL.md new file mode 100644 index 0000000..dc39814 --- /dev/null +++ b/.agents/skills/dart-migrate-to-checks-package/SKILL.md @@ -0,0 +1,118 @@ +--- +name: dart-migrate-to-checks-package +description: Replace the usage of `expect` and similar functions from `package:matcher` to `package:checks` equivalents. +metadata: + model: models/gemini-3.1-pro-preview + last_modified: Fri, 24 Apr 2026 15:15:22 GMT +--- +# Migrating Dart Tests to Package Checks + +## Contents +- [Dependency Management](#dependency-management) +- [Syntax Migration Guidelines](#syntax-migration-guidelines) +- [Utilizing Dart MCP Tools](#utilizing-dart-mcp-tools) +- [Migration Workflow](#migration-workflow) +- [Examples](#examples) + +## Dependency Management +Manage dependencies using the Dart Tooling MCP Server `pub` tool or standard CLI commands. + +- Add `package:checks` as a `dev_dependency` using `dart pub add dev:checks`. +- Remove `package:matcher` if it is explicitly listed in the `pubspec.yaml` (note: it is often transitively included by `package:test`, which is fine). +- Import `package:checks/checks.dart` in all test files undergoing migration. + +## Syntax Migration Guidelines +Transition test assertions from the `package:matcher` syntax to the literate API provided by `package:checks`. + +- **Basic Equality:** Replace `expect(actual, equals(expected))` or `expect(actual, expected)` with `check(actual).equals(expected)`. +- **Type Checking:** Replace `expect(actual, isA())` with `check(actual).isA()`. +- **Property Extraction:** Replace `expect(actual.property, expected)` with `check(actual).has((a) => a.property, 'property name').equals(expected)`. +- **Cascades for Multiple Checks:** Use Dart's cascade operator (`..`) to chain multiple expectations on a single subject. +- **Asynchronous Expectations:** + - If checking a `Future`, `await` the `check` call: `await check(someFuture).completes((r) => r.equals(expected));`. + - If checking a `Stream`, wrap it in a `StreamQueue` for multiple checks, or use `.withQueue` for single/broadcast checks. + +## Migration Workflow + +Copy and use the following checklist to track progress when migrating a test suite: + +- [ ] **Task Progress** + - [ ] Add `package:checks` as a dev dependency. + - [ ] Identify all test files using `package:matcher` (`expect` calls). + - [ ] Import `package:checks/checks.dart` in target test files. + - [ ] Rewrite all `expect(...)` statements to `check(...)` statements. + - [ ] Run static analyzer (`analyze_files`). + - [ ] Run tests (`run_tests`). + +### Feedback Loop: Static Analysis +1. Run the `analyze_files` tool on the modified test directories. +2. Review any static analysis warnings or errors (e.g., missing imports, incorrect generic types on `isA`, unawaited futures). +3. Fix the warnings. +4. Repeat until the analyzer returns zero issues. + +### Feedback Loop: Test Validation +1. Run the `run_tests` tool. +2. If tests fail, review the failure output. `package:checks` provides detailed context (e.g., `Which: has length of <2>`). +3. Adjust the `check()` expectations or the underlying code to resolve the failure. +4. Repeat until all tests pass. + +## Examples + +### Basic Assertions +**Input (`matcher`):** +```dart +expect(someList.length, 1); +expect(someString, startsWith('a')); +expect(someObject, isA()); +``` + +**Output (`checks`):** +```dart +check(someList).length.equals(1); +check(someString).startsWith('a'); +check(someObject).isA(); +``` + +### Composed Expectations +**Input (`matcher`):** +```dart +expect('foo,bar,baz', allOf([ + contains('foo'), + isNot(startsWith('bar')), + endsWith('baz') +])); +``` + +**Output (`checks`):** +```dart +check('foo,bar,baz') + ..contains('foo') + ..not((s) => s.startsWith('bar')) + ..endsWith('baz'); +``` + +### Asynchronous Futures +**Input (`matcher`):** +```dart +expect(Future.value(10), completion(equals(10))); +expect(Future.error('oh no'), throwsA(equals('oh no'))); +``` + +**Output (`checks`):** +```dart +await check(Future.value(10)).completes((it) => it.equals(10)); +await check(Future.error('oh no')).throws().equals('oh no'); +``` + +### Asynchronous Streams +**Input (`matcher`):** +```dart +var stdout = StreamQueue(Stream.fromIterable(['Ready', 'Go'])); +await expectLater(stdout, emitsThrough('Ready')); +``` + +**Output (`checks`):** +```dart +var stdout = StreamQueue(Stream.fromIterable(['Ready', 'Go'])); +await check(stdout).emitsThrough((it) => it.equals('Ready')); +``` diff --git a/.agents/skills/dart-resolve-package-conflicts/SKILL.md b/.agents/skills/dart-resolve-package-conflicts/SKILL.md new file mode 100644 index 0000000..9a7ffdc --- /dev/null +++ b/.agents/skills/dart-resolve-package-conflicts/SKILL.md @@ -0,0 +1,116 @@ +--- +name: dart-resolve-package-conflicts +description: Workflow for fixing package version conflicts. Use this when `pub get` fails due to incompatible package versions. +metadata: + model: models/gemini-3.1-pro-preview + last_modified: Fri, 24 Apr 2026 15:11:14 GMT +--- +# Managing Dart Dependencies + +## Contents +- [Core Concepts](#core-concepts) +- [Version Constraints](#version-constraints) +- [Workflow: Auditing Dependencies](#workflow-auditing-dependencies) +- [Workflow: Upgrading Dependencies](#workflow-upgrading-dependencies) +- [Workflow: Resolving Version Conflicts](#workflow-resolving-version-conflicts) +- [Examples](#examples) + +## Core Concepts + +Dart enforces a strict single-version rule for dependencies: a project and all its transitive dependencies must resolve to a single, shared version of any given package. This prevents runtime type mismatches but introduces the risk of "version lock." + +To mitigate version lock, Dart relies on version constraints rather than pinned versions in the `pubspec.yaml`. The `pubspec.lock` file maintains the exact resolved versions for reproducible builds. + +Understand the output columns of `dart pub outdated`: +* **Current:** The version currently recorded in `pubspec.lock`. +* **Upgradable:** The latest version allowed by the constraints in `pubspec.yaml`. `dart pub upgrade` resolves to this. +* **Resolvable:** The absolute latest version that can be resolved when factoring in all other dependencies in the project. +* **Latest:** The latest published version of the package (excluding prereleases). + +## Version Constraints + +* **Use Caret Syntax:** Always use caret syntax (e.g., `^1.2.3`) for dependencies in `pubspec.yaml`. This allows `pub` to select newer, non-breaking versions (up to, but not including, the next major version) during resolution. +* **Tighten Dev Dependencies:** Set the lower bound of `dev_dependencies` to the exact version currently used. This reduces resolution complexity and prevents older, incompatible dev tools from being selected. +* **Enforce Lockfiles in CI:** Use `dart pub get --enforce-lockfile` in CI/CD pipelines to ensure the exact versions tested locally are used in production. + +## Workflow: Auditing Dependencies + +Run this workflow periodically to identify stale packages that may impact stability or performance. + +**Task Progress:** +- [ ] Run `dart pub outdated`. +- [ ] Review the **Upgradable** column to identify packages that can be updated without modifying `pubspec.yaml`. +- [ ] Review the **Resolvable** column to identify packages that require constraint modifications in `pubspec.yaml` to update. +- [ ] Identify any packages marked as retracted or discontinued. + +## Workflow: Upgrading Dependencies + +Use conditional logic based on the audit results to upgrade dependencies. + +**Task Progress:** +- [ ] **If updating to "Upgradable" versions:** + - [ ] Run `dart pub upgrade`. + - [ ] Run `dart pub upgrade --tighten` to automatically update the lower bounds in `pubspec.yaml` to match the newly resolved versions. +- [ ] **If updating to "Resolvable" versions (Major updates):** + - [ ] Manually edit `pubspec.yaml` to bump the version constraint to match the "Resolvable" column (e.g., change `^0.11.0` to `^0.12.1`). + - [ ] Run `dart pub upgrade` to resolve the new constraints and update `pubspec.lock`. +- [ ] **Feedback Loop:** + - [ ] Run `dart analyze` -> review errors -> fix breaking API changes. + - [ ] Run `dart test` -> review failures -> fix regressions. + +## Workflow: Resolving Version Conflicts + +When `pub` cannot find a set of concrete versions that satisfy all constraints, or when dealing with a retracted package version, manipulate the lockfile surgically. + +**NEVER** delete the entire `pubspec.lock` file and run `dart pub get`. This causes uncontrolled upgrades across the entire dependency graph. + +**Task Progress:** +- [ ] Open `pubspec.lock`. +- [ ] Locate the specific YAML block for the conflicting or retracted package. +- [ ] Delete ONLY that package's entry from the lockfile. +- [ ] Run `dart pub get` to fetch the newest compatible, non-retracted version for that specific package. +- [ ] **Feedback Loop:** + - [ ] Run `dart pub deps` -> verify the dependency graph resolves correctly. + - [ ] If resolution fails, identify the transitive dependency causing the lock, update its constraint in `pubspec.yaml`, and retry. + +## Examples + +### Tightening Constraints +When `dart pub outdated` shows a package is resolvable to a higher minor/patch version, use the `--tighten` flag to update the `pubspec.yaml` automatically. + +**Input (`pubspec.yaml`):** +```yaml +dependencies: + http: ^0.13.0 +``` + +**Command:** +```bash +dart pub upgrade --tighten http +``` + +**Output (`pubspec.yaml`):** +```yaml +dependencies: + http: ^0.13.5 +``` + +### Surgical Lockfile Removal +If `package_a` is retracted or locked in a conflict, remove only its block from `pubspec.lock`. + +**Before (`pubspec.lock`):** +```yaml +packages: + package_a: + dependency: "direct main" + description: + name: package_a + url: "https://pub.dev" + source: hosted + version: "1.0.0" # Retracted version + package_b: + dependency: "direct main" + # ... +``` + +**Action:** Delete the `package_a` block entirely. Leave `package_b` untouched. Run `dart pub get`. diff --git a/.agents/skills/dart-run-static-analysis/SKILL.md b/.agents/skills/dart-run-static-analysis/SKILL.md new file mode 100644 index 0000000..27ca654 --- /dev/null +++ b/.agents/skills/dart-run-static-analysis/SKILL.md @@ -0,0 +1,104 @@ +--- +name: dart-run-static-analysis +description: Execute `dart analyze` to identify warnings and errors, and use `dart fix --apply` to automatically resolve mechanical lint issues. Use during development to ensure code quality and before committing changes. +metadata: + model: models/gemini-3.1-pro-preview + last_modified: Fri, 24 Apr 2026 15:09:34 GMT +--- +# Analyzing and Fixing Dart Code + +## Contents +- [Analysis Configuration](#analysis-configuration) +- [Diagnostic Suppression](#diagnostic-suppression) +- [Workflow: Executing Static Analysis](#workflow-executing-static-analysis) +- [Workflow: Applying Automated Fixes](#workflow-applying-automated-fixes) +- [Examples](#examples) + +## Analysis Configuration + +Configure the Dart analyzer using the `analysis_options.yaml` file located at the package root. + +- **Base Configuration:** Always include a standard rule set (e.g., `package:lints/recommended.yaml` or `package:flutter_lints/flutter.yaml`) using the `include:` directive. +- **Strict Type Checks:** Enable strict type checks under the `analyzer: language:` node to prevent implicit downcasts and dynamic inferences. Set `strict-casts: true`, `strict-inference: true`, and `strict-raw-types: true`. +- **Linter Rules:** Explicitly enable or disable specific rules under the `linter: rules:` node. Use a key-value map (`rule_name: true/false`) when overriding included rules, or a list (`- rule_name`) when defining a fresh set. Do not mix list and map syntax in the same `rules` block. +- **Formatter Configuration:** Configure `dart format` behavior under the `formatter:` node. Set `page_width` (default 80) and `trailing_commas` (`automate` or `preserve`). +- **Analyzer Plugins:** Enable custom diagnostics by adding plugins under the `analyzer: plugins:` node. Ensure the plugin package is added as a `dev_dependency` in `pubspec.yaml`. + +## Diagnostic Suppression + +When a diagnostic (lint or warning) yields a false positive or applies to generated code, suppress it explicitly. + +- **File-level Exclusion:** Use the `analyzer: exclude:` node in `analysis_options.yaml` to exclude entire files or directories (e.g., `**/*.g.dart`) using glob patterns. +- **File-level Suppression:** Add `// ignore_for_file: ` at the top of a Dart file to suppress specific diagnostics for the entire file. Use `// ignore_for_file: type=lint` to suppress all linter rules. +- **Line-level Suppression:** Add `// ignore: ` on the line directly above the offending code, or appended to the end of the offending line. +- **Pubspec Suppression:** Add `# ignore: ` above the offending line in `pubspec.yaml` files (e.g., `# ignore: sort_pub_dependencies`). +- **Plugin Diagnostics:** Prefix the diagnostic code with the plugin name when suppressing plugin-specific issues (e.g., `// ignore: some_plugin/some_code`). + +## Workflow: Executing Static Analysis + +Use this workflow to identify type-related bugs, style violations, and potential runtime errors. + +**Task Progress:** +- [ ] 1. Verify `analysis_options.yaml` exists at the project root. +- [ ] 2. Run the analyzer using the `analyze_files` MCP tool (if available) or the CLI command `dart analyze `. +- [ ] 3. Review the diagnostic output. +- [ ] 4. If info-level issues must be treated as failures, append the `--fatal-infos` flag. +- [ ] 5. Resolve reported errors manually or proceed to the Automated Fixes workflow. + +## Workflow: Applying Automated Fixes + +Use this workflow to resolve outdated API usages, apply quick fixes, and migrate code (e.g., Dart 3 migrations). + +**Task Progress:** +- [ ] 1. Execute a dry run to preview proposed changes using the `dart_fix` MCP tool or CLI command `dart fix --dry-run`. +- [ ] 2. Review the proposed fixes to ensure they align with the intended architecture. +- [ ] 3. If additional fixes are required, verify that the corresponding linter rules are enabled in `analysis_options.yaml`. +- [ ] 4. Apply the fixes using the `dart_fix` MCP tool or CLI command `dart fix --apply`. +- [ ] 5. Format the modified code using the `dart_format` MCP tool or CLI command `dart format .`. +- [ ] 6. Run the static analysis workflow to verify all diagnostics are resolved. + +## Examples + +### Comprehensive `analysis_options.yaml` + +```yaml +include: package:flutter_lints/recommended.yaml + +analyzer: + exclude: + - "**/*.g.dart" + - "lib/generated/**" + language: + strict-casts: true + strict-inference: true + strict-raw-types: true + errors: + todo: ignore + invalid_assignment: warning + missing_return: error + +linter: + rules: + avoid_shadowing_type_parameters: false + await_only_futures: true + use_super_parameters: true + +formatter: + page_width: 100 + trailing_commas: preserve +``` + +### Inline Diagnostic Suppression + +```dart +// Suppress for the entire file +// ignore_for_file: unused_local_variable, dead_code + +void processData() { + // Suppress for a specific line + // ignore: invalid_assignment + int x = ''; + + const y = 10; // ignore: constant_identifier_names +} +``` diff --git a/.agents/skills/dart-use-pattern-matching/SKILL.md b/.agents/skills/dart-use-pattern-matching/SKILL.md new file mode 100644 index 0000000..7455620 --- /dev/null +++ b/.agents/skills/dart-use-pattern-matching/SKILL.md @@ -0,0 +1,146 @@ +--- +name: dart-use-pattern-matching +description: Use switch expressions and pattern matching where appropriate +metadata: + model: models/gemini-3.1-pro-preview + last_modified: Fri, 24 Apr 2026 15:08:55 GMT +--- +# Implementing Dart Patterns + +## Contents +- [Pattern Selection Strategy](#pattern-selection-strategy) +- [Switch Statements vs. Expressions](#switch-statements-vs-expressions) +- [Core Pattern Implementations](#core-pattern-implementations) +- [Workflows](#workflows) +- [Examples](#examples) + +## Pattern Selection Strategy + +Apply specific pattern types based on the data structure and desired outcome. Follow these conditional guidelines: + +* **If validating and extracting from deserialized data (e.g., JSON):** Use Map and List patterns to simultaneously check structure and destructure key-value pairs. +* **If handling multiple return values:** Use Record patterns to destructure fields directly into local variables. +* **If executing type-specific behavior (Algebraic Data Types):** Use Object patterns combined with `sealed` classes to ensure exhaustiveness. +* **If matching numeric ranges or conditions:** Use Relational (`>=`, `<=`) and Logical-and (`&&`) patterns. +* **If multiple cases share logic:** Use Logical-or (`||`) patterns to share a single case body or guard clause. +* **If ignoring specific values:** Use the Wildcard pattern (`_`) or a non-matching Rest element (`...`) in collections. + +## Switch Statements vs. Expressions + +Select the appropriate switch construct based on the execution context: + +* **If producing a value:** Use a **switch expression**. + * Syntax: `switch (value) { pattern => expression, }` + * Rule: Each case must be a single expression. No implicit fallthrough. Must be exhaustive. +* **If executing statements or side effects:** Use a **switch statement**. + * Syntax: `switch (value) { case pattern: statements; }` + * Rule: Empty cases fall through to the next case. Non-empty cases implicitly break (no `break` keyword required). + +## Core Pattern Implementations + +Implement patterns using the following syntax and rules: + +* **Logical-or (`||`):** `pattern1 || pattern2`. Both branches must define the exact same set of variables. +* **Logical-and (`&&`):** `pattern1 && pattern2`. Branches must *not* define overlapping variables. +* **Relational:** `==`, `!=`, `<`, `>`, `<=`, `>=` followed by a constant expression. +* **Cast (`as`):** `pattern as Type`. Throws if the value does not match the type. Use to forcibly assert types during destructuring. +* **Null-check (`?`):** `pattern?`. Fails the match if the value is null. Binds the variable to the non-nullable base type. +* **Null-assert (`!`):** `pattern!`. Throws if the value is null. +* **Variable:** `var name` or `Type name`. Binds the matched value to a new local variable. +* **Wildcard (`_`):** Matches any value and discards it. +* **List:** `[pattern1, pattern2]`. Matches lists of exact length unless a Rest element (`...` or `...var rest`) is used. +* **Map:** `{"key": pattern}`. Matches maps containing the specified keys. Ignores unmatched keys. +* **Record:** `(pattern1, named: pattern2)`. Matches records of the exact shape. Use `:var name` to infer the getter name. +* **Object:** `ClassName(field: pattern)`. Matches instances of `ClassName`. Use `:var field` to infer the getter name. + +## Workflows + +### Task Progress: Implementing Pattern Matching +Copy this checklist to track progress when implementing complex pattern matching logic: + +- [ ] Identify the data structure being evaluated (JSON, Record, Class, Enum). +- [ ] Select the appropriate switch construct (Expression for values, Statement for side-effects). +- [ ] Define the required patterns (Object, Map, List, Record). +- [ ] Extract required data using Variable patterns (`var x`, `:var y`). +- [ ] Apply Guard clauses (`when condition`) for logic that cannot be expressed via patterns. +- [ ] Handle unmatched cases using a Wildcard (`_`) or `default` clause (if not using a sealed class). +- [ ] Run exhaustiveness validator. + +### Feedback Loop: Exhaustiveness Checking +When switching over `sealed` classes or enums, you must ensure all subtypes are handled. + +1. **Run validator:** Execute `dart analyze`. +2. **Review errors:** Look for "The type 'X' is not exhaustively matched by the switch cases" errors. +3. **Fix:** Add the missing Object patterns for the unhandled subtypes, or add a Wildcard (`_`) case if a default fallback is acceptable. + +## Examples + +### JSON Validation and Destructuring +Use Map and List patterns to validate structure and extract data in a single step. + +**Input:** +```dart +var data = { + 'user': ['Lily', 13], +}; +``` + +**Implementation:** +```dart +if (data case {'user': [String name, int age]}) { + print('User $name is $age years old.'); +} else { + print('Invalid JSON structure.'); +} +``` + +### Algebraic Data Types (Sealed Classes) +Use Object patterns with switch expressions to handle family types exhaustively. + +**Implementation:** +```dart +sealed class Shape {} + +class Square implements Shape { + final double length; + Square(this.length); +} + +class Circle implements Shape { + final double radius; + Circle(this.radius); +} + +// Switch expression guarantees exhaustiveness due to `sealed` modifier. +double calculateArea(Shape shape) => switch (shape) { + Square(length: var l) => l * l, + Circle(:var radius) => math.pi * radius * radius, +}; +``` + +### Variable Swapping and Destructuring +Use variable assignment patterns to swap values or extract record fields without temporary variables. + +**Implementation:** +```dart +var (a, b) = ('left', 'right'); +(b, a) = (a, b); // Swap values + +// Destructuring a function return +var (name, age) = getUserInfo(); +``` + +### Guard Clauses and Logical-or +Use `when` to evaluate arbitrary conditions after a pattern matches. + +**Implementation:** +```dart +switch (shape) { + case Square(size: var s) || Circle(size: var s) when s > 0: + print('Valid symmetric shape with size $s'); + case Square() || Circle(): + print('Invalid or empty shape'); + default: + print('Unknown shape'); +} +``` diff --git a/.agents/skills/flutter-add-integration-test/SKILL.md b/.agents/skills/flutter-add-integration-test/SKILL.md new file mode 100644 index 0000000..60902f1 --- /dev/null +++ b/.agents/skills/flutter-add-integration-test/SKILL.md @@ -0,0 +1,163 @@ +--- +name: flutter-add-integration-test +description: Configures Flutter Driver for app interaction and converts MCP actions into permanent integration tests. Use when adding integration testing to a project, exploring UI components via MCP, or automating user flows with the integration_test package. +metadata: + model: models/gemini-3.1-pro-preview + last_modified: Tue, 21 Apr 2026 18:29:20 GMT +--- +# Implementing Flutter Integration Tests + +## Contents +- [Project Setup and Dependencies](#project-setup-and-dependencies) +- [Interactive Exploration via MCP](#interactive-exploration-via-mcp) +- [Test Authoring Guidelines](#test-authoring-guidelines) +- [Execution and Profiling](#execution-and-profiling) +- [Workflow: End-to-End Integration Testing](#workflow-end-to-end-integration-testing) +- [Examples](#examples) + +## Project Setup and Dependencies + +Configure the project to support integration testing and Flutter Driver extensions. + +1. Add required development dependencies to `pubspec.yaml`: + ```bash + flutter pub add 'dev:integration_test:{"sdk":"flutter"}' + flutter pub add 'dev:flutter_test:{"sdk":"flutter"}' + ``` +2. Enable the Flutter Driver extension in your application entry point (typically `lib/main.dart` or a dedicated `lib/main_test.dart`): + - Import `package:flutter_driver/driver_extension.dart`. + - Call `enableFlutterDriverExtension();` before `runApp()`. +3. Add `Key` parameters (e.g., `ValueKey('login_button')`) to critical widgets in the application code to ensure reliable targeting during tests. + +## Interactive Exploration via MCP + +Use the Dart/Flutter MCP server tools to interactively explore and manipulate the application state before writing static tests. + +- **Launch**: Execute `launch_app` with `target: "lib/main_test.dart"` to start the application and acquire the DTD URI. +- **Inspect**: Execute `get_widget_tree` to discover available `Key`s, `Text` nodes, and widget `Type`s. +- **Interact**: Execute `tap`, `enter_text`, and `scroll` to simulate user flows. +- **Wait**: Always execute `waitFor` or verify state with `get_health` when navigating or triggering animations. +- **Troubleshoot Unmounted Widgets**: If a widget is not found in the tree, it may be lazily loaded in a `SliverList` or `ListView`. Execute `scroll` or `scrollIntoView` to force the widget to mount before interacting with it. + +## Test Authoring Guidelines + +Structure integration tests using the `flutter_test` API paradigm. + +- Create a dedicated `integration_test/` directory at the project root. +- Name all test files using the `_test.dart` convention. +- Initialize the binding by calling `IntegrationTestWidgetsFlutterBinding.ensureInitialized();` at the start of `main()`. +- Load the application UI using `await tester.pumpWidget(MyApp());`. +- Trigger frames and wait for animations to complete using `await tester.pumpAndSettle();` after interactions like `tester.tap()`. +- Assert widget visibility using `expect(find.byKey(ValueKey('foo')), findsOneWidget);` or `findsNothing`. +- Scroll to specific off-screen widgets using `await tester.scrollUntilVisible(itemFinder, 500.0, scrollable: listFinder);`. + +**Conditional Logic for Legacy `flutter_driver`:** +- If maintaining or migrating legacy `flutter_driver` tests, use `driver.waitFor()`, `driver.waitForAbsent()`, `driver.tap()`, and `driver.scroll()` instead of the `WidgetTester` APIs. + +## Execution and Profiling + +Execute tests using the `flutter drive` command. Require a host driver script located in `test_driver/integration_test.dart` that calls `integrationDriver()`. + +**Conditional Execution Targets:** +- **If testing on Chrome:** Launch `chromedriver --port=4444` in a separate terminal, then run: + `flutter drive --driver=test_driver/integration_test.dart --target=integration_test/app_test.dart -d chrome` +- **If testing headless web:** Run with `-d web-server`. +- **If testing on Android (Local):** Run `flutter drive --driver=test_driver/integration_test.dart --target=integration_test/app_test.dart`. +- **If testing on Firebase Test Lab (Android):** + 1. Build debug APK: `flutter build apk --debug` + 2. Build test APK: `./gradlew app:assembleAndroidTest` + 3. Upload both APKs to the Firebase Test Lab console. + +## Workflow: End-to-End Integration Testing + +Copy and follow this checklist to implement and verify integration tests. + +- [ ] **Task Progress: Setup** + - [ ] Add `integration_test` and `flutter_test` to `pubspec.yaml`. + - [ ] Inject `enableFlutterDriverExtension()` into the app entry point. + - [ ] Assign `ValueKey`s to target widgets. +- [ ] **Task Progress: Exploration** + - [ ] Run `launch_app` via MCP. + - [ ] Map the widget tree using `get_widget_tree`. + - [ ] Validate interaction paths using MCP tools (`tap`, `enter_text`). +- [ ] **Task Progress: Authoring** + - [ ] Create `integration_test/app_test.dart`. + - [ ] Write test cases using `WidgetTester` APIs. + - [ ] Create `test_driver/integration_test.dart` with `integrationDriver()`. +- [ ] **Task Progress: Execution & Feedback Loop** + - [ ] Run `flutter drive --driver=test_driver/integration_test.dart --target=integration_test/app_test.dart`. + - [ ] **Feedback Loop**: Review test output -> If `PumpAndSettleTimedOutException` occurs, check for infinite animations -> If widget not found, add `scrollUntilVisible` -> Re-run test until passing. + +## Examples + +### Standard Integration Test (`integration_test/app_test.dart`) + +```dart +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:integration_test/integration_test.dart'; +import 'package:my_app/main.dart'; + +void main() { + IntegrationTestWidgetsFlutterBinding.ensureInitialized(); + + group('End-to-end test', () { + testWidgets('tap on the floating action button, verify counter', (tester) async { + // Load app widget. + await tester.pumpWidget(const MyApp()); + + // Verify the counter starts at 0. + expect(find.text('0'), findsOneWidget); + + // Find the floating action button to tap on. + final fab = find.byKey(const ValueKey('increment')); + + // Emulate a tap on the floating action button. + await tester.tap(fab); + + // Trigger a frame and wait for animations. + await tester.pumpAndSettle(); + + // Verify the counter increments by 1. + expect(find.text('1'), findsOneWidget); + }); + }); +} +``` + +### Host Driver Script (`test_driver/integration_test.dart`) + +```dart +import 'package:integration_test/integration_test_driver.dart'; + +Future main() => integrationDriver(); +``` + +### Performance Profiling Driver Script (`test_driver/perf_driver.dart`) + +Use this driver script if you wrap your test actions in `binding.traceAction()` to capture performance metrics. + +```dart +import 'package:flutter_driver/flutter_driver.dart' as driver; +import 'package:integration_test/integration_test_driver.dart'; + +Future main() { + return integrationDriver( + responseDataCallback: (data) async { + if (data != null) { + final timeline = driver.Timeline.fromJson( + data['scrolling_timeline'] as Map, + ); + + final summary = driver.TimelineSummary.summarize(timeline); + + await summary.writeTimelineToFile( + 'scrolling_timeline', + pretty: true, + includeSummary: true, + ); + } + }, + ); +} +``` diff --git a/.agents/skills/flutter-add-widget-preview/SKILL.md b/.agents/skills/flutter-add-widget-preview/SKILL.md new file mode 100644 index 0000000..6ba6894 --- /dev/null +++ b/.agents/skills/flutter-add-widget-preview/SKILL.md @@ -0,0 +1,145 @@ +--- +name: flutter-add-widget-preview +description: Adds interactive widget previews to the project using the previews.dart system. Use when creating new UI components or updating existing screens to ensure consistent design and interactive testing. +metadata: + model: models/gemini-3.1-pro-preview + last_modified: Tue, 21 Apr 2026 20:05:23 GMT +--- +# Previewing Flutter Widgets + +## Contents +- [Preview Guidelines](#preview-guidelines) +- [Handling Limitations](#handling-limitations) +- [Workflows](#workflows) +- [Examples](#examples) + +## Preview Guidelines + +Use the Flutter Widget Previewer to render widgets in real-time, isolated from the full application context. + +- **Target Elements:** Apply the `@Preview` annotation to top-level functions, static methods within a class, or public widget constructors/factories that have no required arguments and return a `Widget` or `WidgetBuilder`. +- **Imports:** Always import `package:flutter/widget_previews.dart` to access the preview annotations. +- **Custom Annotations:** Extend the `Preview` class to create custom annotations that inject common properties (e.g., themes, wrappers) across multiple widgets. +- **Multiple Configurations:** Apply multiple `@Preview` annotations to a single target to generate multiple preview instances. Alternatively, extend `MultiPreview` to encapsulate common multi-preview configurations. +- **Runtime Transformations:** Override the `transform()` method in custom `Preview` or `MultiPreview` classes to modify preview configurations dynamically at runtime (e.g., generating names based on dynamic values, which is impossible in a `const` context). + +## Handling Limitations + +Adhere to the following constraints when authoring previewable widgets, as the Widget Previewer runs in a web environment: + +- **No Native APIs:** Do not use native plugins or APIs from `dart:io` or `dart:ffi`. Widgets with transitive dependencies on `dart:io` or `dart:ffi` will throw exceptions upon invocation. Use conditional imports to mock or bypass these in preview mode. +- **Asset Paths:** Use package-based paths for assets loaded via `dart:ui` `fromAsset` APIs (e.g., `packages/my_package_name/assets/my_image.png` instead of `assets/my_image.png`). +- **Public Callbacks:** Ensure all callback arguments provided to preview annotations are public and constant to satisfy code generation requirements. +- **Constraints:** Apply explicit constraints using the `size` parameter in the `@Preview` annotation if your widget is unconstrained, as the previewer defaults to constraining them to approximately half the viewport. + +## Workflows + +### Creating a Widget Preview +Copy and track this checklist when implementing a new widget preview: + +- [ ] Import `package:flutter/widget_previews.dart`. +- [ ] Identify a valid target (top-level function, static method, or parameter-less public constructor). +- [ ] Apply the `@Preview` annotation to the target. +- [ ] Configure preview parameters (`name`, `group`, `size`, `theme`, `brightness`, etc.) as needed. +- [ ] If applying the same configuration to multiple widgets, extract the configuration into a custom class extending `Preview`. + +### Interacting with Previews +Follow the appropriate conditional workflow to launch and interact with the Widget Previewer: + +**If using a supported IDE (Android Studio, IntelliJ, VS Code with Flutter 3.38+):** +1. Launch the IDE. The Widget Previewer starts automatically. +2. Open the "Flutter Widget Preview" tab in the sidebar. +3. Toggle "Filter previews by selected file" at the bottom left if you want to view previews outside the currently active file. + +**If using the Command Line:** +1. Navigate to the Flutter project's root directory. +2. Run `flutter widget-preview start`. +3. View the automatically opened Chrome environment. + +**Feedback Loop: Preview Iteration** +1. Modify the widget code or preview configuration. +2. Observe the automatic update in the Widget Previewer. +3. If global state (e.g., static initializers) was modified: Click the global hot restart button at the bottom right. +4. If only the local widget state needs resetting: Click the individual hot restart button on the specific preview card. +5. Review errors in the IDE/CLI console -> fix -> repeat. + +## Examples + +### Basic Preview +```dart +import 'package:flutter/widget_previews.dart'; +import 'package:flutter/material.dart'; + +@Preview(name: 'My Sample Text', group: 'Typography') +Widget mySampleText() { + return const Text('Hello, World!'); +} +``` + +### Custom Preview with Runtime Transformation +```dart +import 'package:flutter/widget_previews.dart'; +import 'package:flutter/material.dart'; + +final class TransformativePreview extends Preview { + const TransformativePreview({ + super.name, + super.group, + }); + + PreviewThemeData _themeBuilder() { + return PreviewThemeData( + materialLight: ThemeData.light(), + materialDark: ThemeData.dark(), + ); + } + + @override + Preview transform() { + final originalPreview = super.transform(); + final builder = originalPreview.toBuilder(); + + builder + ..name = 'Transformed - ${originalPreview.name}' + ..theme = _themeBuilder; + + return builder.toPreview(); + } +} + +@TransformativePreview(name: 'Custom Themed Button') +Widget myButton() => const ElevatedButton(onPressed: null, child: Text('Click')); +``` + +### MultiPreview Implementation +```dart +import 'package:flutter/widget_previews.dart'; +import 'package:flutter/material.dart'; + +/// Creates light and dark mode previews automatically. +final class MultiBrightnessPreview extends MultiPreview { + const MultiBrightnessPreview({required this.name}); + + final String name; + + @override + List get previews => const [ + Preview(brightness: Brightness.light), + Preview(brightness: Brightness.dark), + ]; + + @override + List transform() { + final previews = super.transform(); + return previews.map((preview) { + final builder = preview.toBuilder() + ..group = 'Brightness' + ..name = '$name - ${preview.brightness!.name}'; + return builder.toPreview(); + }).toList(); + } +} + +@MultiBrightnessPreview(name: 'Primary Card') +Widget cardPreview() => const Card(child: Padding(padding: EdgeInsets.all(8.0), child: Text('Content'))); +``` diff --git a/.agents/skills/flutter-add-widget-test/SKILL.md b/.agents/skills/flutter-add-widget-test/SKILL.md new file mode 100644 index 0000000..01ac7ac --- /dev/null +++ b/.agents/skills/flutter-add-widget-test/SKILL.md @@ -0,0 +1,154 @@ +--- +name: flutter-add-widget-test +description: Implement a component-level test using `WidgetTester` to verify UI rendering and user interactions (tapping, scrolling, entering text). Use when validating that a specific widget displays correct data and responds to events as expected. +metadata: + model: models/gemini-3.1-pro-preview + last_modified: Tue, 21 Apr 2026 21:15:41 GMT +--- +# Writing Flutter Widget Tests + +## Contents +- [Setup & Configuration](#setup--configuration) +- [Core Components](#core-components) +- [Workflow: Implementing a Widget Test](#workflow-implementing-a-widget-test) +- [Interaction & State Management](#interaction--state-management) +- [Examples](#examples) + +## Setup & Configuration + +Ensure the testing environment is properly configured before authoring widget tests. + +1. Add the `flutter_test` dependency to the `dev_dependencies` section of `pubspec.yaml`. +2. Place all test files in the `test/` directory at the root of the project. +3. Suffix all test file names with `_test.dart` (e.g., `widget_test.dart`). + +## Core Components + +Utilize the following `flutter_test` components to interact with and validate the widget tree: + +* **`WidgetTester`**: The primary interface for building and interacting with widgets in the test environment. Provided automatically by the `testWidgets()` function. +* **`Finder`**: Locates widgets in the test environment (e.g., `find.text('Submit')`, `find.byType(TextField)`, `find.byKey(Key('submit_btn'))`). +* **`Matcher`**: Verifies the presence or state of widgets located by a `Finder` (e.g., `findsOneWidget`, `findsNothing`, `findsNWidgets(2)`, `matchesGoldenFile`). + +## Workflow: Implementing a Widget Test + +Copy the following checklist to track progress when implementing a new widget test. + +### Task Progress +- [ ] **Step 1: Define the test.** Use `testWidgets('description', (WidgetTester tester) async { ... })`. +- [ ] **Step 2: Build the widget.** Call `await tester.pumpWidget(MyWidget())` to render the UI. Wrap the widget in a `MaterialApp` or `Directionality` widget if it requires inherited directional or theme data. +- [ ] **Step 3: Locate elements.** Instantiate `Finder` objects for the target widgets. +- [ ] **Step 4: Verify initial state.** Use `expect(finder, matcher)` to validate the initial render. +- [ ] **Step 5: Simulate interactions.** Execute gestures or inputs (e.g., `await tester.tap(buttonFinder)`). +- [ ] **Step 6: Rebuild the tree.** Call `await tester.pump()` or `await tester.pumpAndSettle()` to process state changes. +- [ ] **Step 7: Verify updated state.** Use `expect()` to validate the UI after the interaction. +- [ ] **Step 8: Run and validate.** Execute `flutter test test/your_test_file_test.dart`. +- [ ] **Step 9: Feedback Loop.** Review test output -> identify failing matchers -> adjust widget logic or test assertions -> re-run until passing. + +## Interaction & State Management + +Apply the following conditional logic based on the type of interaction or state change being tested: + +* **If testing static rendering:** Call `await tester.pumpWidget()` once, then immediately run `expect()` assertions. +* **If testing standard state changes (e.g., button taps):** + 1. Call `await tester.tap(finder)`. + 2. Call `await tester.pump()` to trigger a single frame rebuild. +* **If testing animations, transitions, or asynchronous UI updates:** + 1. Trigger the action (e.g., `await tester.drag(finder, Offset(500, 0))`). + 2. Call `await tester.pumpAndSettle()` to repeatedly pump frames until no more frames are scheduled (animation completes). +* **If testing text input:** Call `await tester.enterText(textFieldFinder, 'Input string')`. +* **If testing items in a dynamic or long list:** Call `await tester.scrollUntilVisible(itemFinder, 500.0, scrollable: listFinder)` to ensure the target widget is rendered before interacting with it. + +## Examples + +### High-Fidelity Widget Test Implementation + +**Target Widget (`lib/todo_list.dart`):** +```dart +import 'package:flutter/material.dart'; + +class TodoList extends StatefulWidget { + const TodoList({super.key}); + + @override + State createState() => _TodoListState(); +} + +class _TodoListState extends State { + final todos = []; + final controller = TextEditingController(); + + @override + Widget build(BuildContext context) { + return MaterialApp( + home: Scaffold( + body: Column( + children: [ + TextField(controller: controller), + Expanded( + child: ListView.builder( + itemCount: todos.length, + itemBuilder: (context, index) { + final todo = todos[index]; + return Dismissible( + key: Key('$todo$index'), + onDismissed: (_) => setState(() => todos.removeAt(index)), + child: ListTile(title: Text(todo)), + ); + }, + ), + ), + ], + ), + floatingActionButton: FloatingActionButton( + onPressed: () { + setState(() { + todos.add(controller.text); + controller.clear(); + }); + }, + child: const Icon(Icons.add), + ), + ), + ); + } +} +``` + +**Test Implementation (`test/todo_list_test.dart`):** +```dart +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:my_app/todo_list.dart'; + +void main() { + testWidgets('Add and remove a todo item', (WidgetTester tester) async { + // 1. Build the widget + await tester.pumpWidget(const TodoList()); + + // 2. Verify initial state + expect(find.byType(ListTile), findsNothing); + + // 3. Enter text into the TextField + await tester.enterText(find.byType(TextField), 'Buy groceries'); + + // 4. Tap the add button + await tester.tap(find.byType(FloatingActionButton)); + + // 5. Rebuild the widget to reflect the new state + await tester.pump(); + + // 6. Verify the item was added + expect(find.text('Buy groceries'), findsOneWidget); + + // 7. Swipe the item to dismiss it + await tester.drag(find.byType(Dismissible), const Offset(500, 0)); + + // 8. Build the widget until the dismiss animation ends + await tester.pumpAndSettle(); + + // 9. Verify the item was removed + expect(find.text('Buy groceries'), findsNothing); + }); +} +``` diff --git a/.agents/skills/flutter-apply-architecture-best-practices/SKILL.md b/.agents/skills/flutter-apply-architecture-best-practices/SKILL.md new file mode 100644 index 0000000..791994b --- /dev/null +++ b/.agents/skills/flutter-apply-architecture-best-practices/SKILL.md @@ -0,0 +1,162 @@ +--- +name: flutter-apply-architecture-best-practices +description: Architects a Flutter application using the recommended layered approach (UI, Logic, Data). Use when structuring a new project or refactoring for scalability. +metadata: + model: models/gemini-3.1-pro-preview + last_modified: Tue, 21 Apr 2026 20:11:20 GMT +--- +# Architecting Flutter Applications + +## Contents +- [Architectural Layers](#architectural-layers) +- [Project Structure](#project-structure) +- [Workflow: Implementing a New Feature](#workflow-implementing-a-new-feature) +- [Examples](#examples) + +## Architectural Layers + +Enforce strict Separation of Concerns by dividing the application into distinct layers. Never mix UI rendering with business logic or data fetching. + +### UI Layer (Presentation) +Implement the MVVM (Model-View-ViewModel) pattern to manage UI state and logic. +* **Views:** Write reusable, lean widgets. Restrict logic in Views to UI-specific operations (e.g., animations, layout constraints, simple routing). Pass all required data from the ViewModel. +* **ViewModels:** Manage UI state and handle user interactions. Extend `ChangeNotifier` (or use `Listenable`) to expose state. Expose immutable state snapshots to the View. Inject Repositories into ViewModels via the constructor. + +### Data Layer +Implement the Repository pattern to isolate data access logic and create a single source of truth. +* **Services:** Create stateless classes to wrap external APIs (HTTP clients, local databases, platform plugins). Return raw API models or `Result` wrappers. +* **Repositories:** Consume one or more Services. Transform raw API models into clean Domain Models. Handle caching, offline synchronization, and retry logic. Expose Domain Models to ViewModels. + +### Logic Layer (Domain - Optional) +* **Use Cases:** Implement this layer only if the application contains complex business logic that clutters the ViewModel, or if logic must be reused across multiple ViewModels. Extract this logic into dedicated Use Case (interactor) classes that sit between ViewModels and Repositories. + +## Project Structure + +Organize the codebase using a hybrid approach: group UI components by feature, and group Data/Domain components by type. + +```text +lib/ +├── data/ +│ ├── models/ # API models +│ ├── repositories/ # Repository implementations +│ └── services/ # API clients, local storage wrappers +├── domain/ +│ ├── models/ # Clean domain models +│ └── use_cases/ # Optional business logic classes +└── ui/ + ├── core/ # Shared widgets, themes, typography + └── features/ + └── [feature_name]/ + ├── view_models/ + └── views/ +``` + +## Workflow: Implementing a New Feature + +Follow this sequential workflow when adding a new feature to the application. Copy the checklist to track progress. + +### Task Progress +- [ ] **Step 1: Define Domain Models.** Create immutable data classes for the feature using `freezed` or `built_value`. +- [ ] **Step 2: Implement Services.** Create or update Service classes to handle external API communication. +- [ ] **Step 3: Implement Repositories.** Create the Repository to consume Services and return Domain Models. +- [ ] **Step 4: Apply Conditional Logic (Domain Layer).** + - *If the feature requires complex data transformation or cross-repository logic:* Create a Use Case class. + - *If the feature is a simple CRUD operation:* Skip to Step 5. +- [ ] **Step 5: Implement the ViewModel.** Create the ViewModel extending `ChangeNotifier`. Inject required Repositories/Use Cases. Expose immutable state and command methods. +- [ ] **Step 6: Implement the View.** Create the UI widget. Use `ListenableBuilder` or `AnimatedBuilder` to listen to ViewModel changes. +- [ ] **Step 7: Inject Dependencies.** Register the new Service, Repository, and ViewModel in the dependency injection container (e.g., `provider` or `get_it`). +- [ ] **Step 8: Run Validator.** Execute unit tests for the ViewModel and Repository. + - *Feedback Loop:* Run tests -> Review failures -> Fix logic -> Re-run until passing. + +## Examples + +### Data Layer: Service and Repository + +```dart +// 1. Service (Raw API interaction) +class ApiClient { + Future fetchUser(String id) async { + // HTTP GET implementation... + } +} + +// 2. Repository (Single source of truth, returns Domain Model) +class UserRepository { + UserRepository({required ApiClient apiClient}) : _apiClient = apiClient; + + final ApiClient _apiClient; + User? _cachedUser; + + Future getUser(String id) async { + if (_cachedUser != null) return _cachedUser!; + + final apiModel = await _apiClient.fetchUser(id); + _cachedUser = User(id: apiModel.id, name: apiModel.fullName); // Transform to Domain Model + return _cachedUser!; + } +} +``` + +### UI Layer: ViewModel and View + +```dart +// 3. ViewModel (State management and presentation logic) +class ProfileViewModel extends ChangeNotifier { + ProfileViewModel({required UserRepository userRepository}) + : _userRepository = userRepository; + + final UserRepository _userRepository; + + User? _user; + User? get user => _user; + + bool _isLoading = false; + bool get isLoading => _isLoading; + + Future loadProfile(String id) async { + _isLoading = true; + notifyListeners(); + + try { + _user = await _userRepository.getUser(id); + } finally { + _isLoading = false; + notifyListeners(); + } + } +} + +// 4. View (Dumb UI component) +class ProfileView extends StatelessWidget { + const ProfileView({super.key, required this.viewModel}); + + final ProfileViewModel viewModel; + + @override + Widget build(BuildContext context) { + return ListenableBuilder( + listenable: viewModel, + builder: (context, _) { + if (viewModel.isLoading) { + return const Center(child: CircularProgressIndicator()); + } + + final user = viewModel.user; + if (user == null) { + return const Center(child: Text('User not found')); + } + + return Column( + children: [ + Text(user.name), + ElevatedButton( + onPressed: () => viewModel.loadProfile(user.id), + child: const Text('Refresh'), + ), + ], + ); + }, + ); + } +} +``` diff --git a/.agents/skills/flutter-build-responsive-layout/SKILL.md b/.agents/skills/flutter-build-responsive-layout/SKILL.md new file mode 100644 index 0000000..b85bfd7 --- /dev/null +++ b/.agents/skills/flutter-build-responsive-layout/SKILL.md @@ -0,0 +1,139 @@ +--- +name: flutter-build-responsive-layout +description: Use `LayoutBuilder`, `MediaQuery`, or `Expanded/Flexible` to create a layout that adapts to different screen sizes. Use when you need the UI to look good on both mobile and tablet/desktop form factors. +metadata: + model: models/gemini-3.1-pro-preview + last_modified: Tue, 21 Apr 2026 20:17:40 GMT +--- +# Implementing Adaptive Layouts + +## Contents +- [Space Measurement Guidelines](#space-measurement-guidelines) +- [Widget Sizing and Constraints](#widget-sizing-and-constraints) +- [Device and Orientation Behaviors](#device-and-orientation-behaviors) +- [Workflow: Constructing an Adaptive Layout](#workflow-constructing-an-adaptive-layout) +- [Workflow: Optimizing for Large Screens](#workflow-optimizing-for-large-screens) +- [Examples](#examples) + +## Space Measurement Guidelines +Determine the available space accurately to ensure layouts adapt to the app window, not just the physical device. + +* **Use `MediaQuery.sizeOf(context)`** to get the size of the entire app window. +* **Use `LayoutBuilder`** to make layout decisions based on the parent widget's allocated space. Evaluate `constraints.maxWidth` to determine the appropriate widget tree to return. +* **Do not use `MediaQuery.orientationOf` or `OrientationBuilder`** near the top of the widget tree to switch layouts. Device orientation does not accurately reflect the available app window space. +* **Do not check for hardware types** (e.g., "phone" vs. "tablet"). Flutter apps run in resizable windows, multi-window modes, and picture-in-picture. Base all layout decisions strictly on available window space. + +## Widget Sizing and Constraints +Understand and apply Flutter's core layout rule: **Constraints go down. Sizes go up. Parent sets position.** + +* **Distribute Space:** Use `Expanded` and `Flexible` within `Row`, `Column`, or `Flex` widgets. + * Use `Expanded` to force a child to fill all remaining available space (equivalent to `Flexible` with `fit: FlexFit.tight` and a `flex` factor of 1.0). + * Use `Flexible` to allow a child to size itself up to a specific limit while still expanding/contracting. Use the `flex` factor to define the ratio of space consumption among siblings. +* **Constrain Width:** Prevent widgets from consuming all horizontal space on large screens. Wrap widgets like `GridView` or `ListView` in a `ConstrainedBox` or `Container` and define a `maxWidth` in the `BoxConstraints`. +* **Lazy Rendering:** Always use `ListView.builder` or `GridView.builder` when rendering lists with an unknown or large number of items. + +## Device and Orientation Behaviors +Ensure the app behaves correctly across all device form factors and input methods. + +* **Do not lock screen orientation.** Locking orientation causes severe layout issues on foldable devices, often resulting in letterboxing (the app centered with black borders). Android large format tiers require both portrait and landscape support. +* **Fallback for Locked Orientation:** If business requirements strictly mandate a locked orientation, use the `Display API` to retrieve physical screen dimensions instead of `MediaQuery`. `MediaQuery` fails to receive the larger window size in compatibility modes. +* **Support Multiple Inputs:** Implement support for basic mice, trackpads, and keyboard shortcuts. Ensure touch targets are appropriately sized and keyboard navigation is accessible. + +## Workflow: Constructing an Adaptive Layout + +Follow this workflow to implement a layout that adapts to the available `BoxConstraints`. + +**Task Progress:** +- [ ] Identify the target widget that requires adaptive behavior. +- [ ] Wrap the widget tree in a `LayoutBuilder`. +- [ ] Extract the `constraints.maxWidth` from the builder callback. +- [ ] Define an adaptive breakpoint (e.g., `largeScreenMinWidth = 600`). +- [ ] **If `maxWidth > largeScreenMinWidth`:** Return a large-screen layout (e.g., a `Row` placing a navigation sidebar and content area side-by-side). +- [ ] **If `maxWidth <= largeScreenMinWidth`:** Return a small-screen layout (e.g., a `Column` or standard navigation-style approach). +- [ ] Run validator -> resize the application window -> review layout transitions -> fix overflow errors. + +## Workflow: Optimizing for Large Screens + +Follow this workflow to prevent UI elements from stretching unnaturally on large displays. + +**Task Progress:** +- [ ] Identify full-width components (e.g., `ListView`, text blocks, forms). +- [ ] **If optimizing a list:** Convert `ListView.builder` to `GridView.builder` using `SliverGridDelegateWithMaxCrossAxisExtent` to automatically adjust column counts based on window size. +- [ ] **If optimizing a form or text block:** Wrap the component in a `ConstrainedBox`. +- [ ] Apply `BoxConstraints(maxWidth: [optimal_width])` to the `ConstrainedBox`. +- [ ] Wrap the `ConstrainedBox` in a `Center` widget to keep the constrained content centered on large screens. +- [ ] Run validator -> test on desktop/tablet target -> review horizontal stretching -> adjust `maxWidth` or grid extents. + +## Examples + +### Adaptive Layout using LayoutBuilder +Demonstrates switching between a mobile and desktop layout based on available width. + +```dart +import 'package:flutter/material.dart'; + +const double largeScreenMinWidth = 600.0; + +class AdaptiveLayout extends StatelessWidget { + const AdaptiveLayout({super.key}); + + @override + Widget build(BuildContext context) { + return LayoutBuilder( + builder: (context, constraints) { + if (constraints.maxWidth > largeScreenMinWidth) { + return _buildLargeScreenLayout(); + } else { + return _buildSmallScreenLayout(); + } + }, + ); + } + + Widget _buildLargeScreenLayout() { + return Row( + children: [ + const SizedBox(width: 250, child: Placeholder(color: Colors.blue)), + const VerticalDivider(width: 1), + Expanded(child: const Placeholder(color: Colors.green)), + ], + ); + } + + Widget _buildSmallScreenLayout() { + return const Placeholder(color: Colors.green); + } +} +``` + +### Constraining Width on Large Screens +Demonstrates preventing a widget from consuming all horizontal space. + +```dart +import 'package:flutter/material.dart'; + +class ConstrainedContent extends StatelessWidget { + const ConstrainedContent({super.key}); + + @override + Widget build(BuildContext context) { + return Scaffold( + body: Center( + child: ConstrainedBox( + constraints: const BoxConstraints( + maxWidth: 800.0, // Maximum width for readability + ), + child: ListView.builder( + itemCount: 50, + itemBuilder: (context, index) { + return ListTile( + title: Text('Item $index'), + ); + }, + ), + ), + ), + ); + } +} +``` diff --git a/.agents/skills/flutter-fix-layout-issues/SKILL.md b/.agents/skills/flutter-fix-layout-issues/SKILL.md new file mode 100644 index 0000000..3804a3c --- /dev/null +++ b/.agents/skills/flutter-fix-layout-issues/SKILL.md @@ -0,0 +1,130 @@ +--- +name: flutter-fix-layout-issues +description: Fixes Flutter layout errors (overflows, unbounded constraints) using Dart and Flutter MCP tools. Use when addressing "RenderFlex overflowed", "Vertical viewport was given unbounded height", or similar layout issues. +metadata: + model: models/gemini-3.1-pro-preview + last_modified: Tue, 21 Apr 2026 19:45:59 GMT +--- +# Resolving Flutter Layout Errors + +## Contents +- [Constraint Violation Diagnostics](#constraint-violation-diagnostics) +- [Layout Error Resolution Workflow](#layout-error-resolution-workflow) +- [Examples](#examples) + +## Constraint Violation Diagnostics + +Flutter layout operates on a strict rule: **Constraints go down. Sizes go up. Parent sets position.** Layout errors occur when this negotiation fails, typically due to unbounded constraints or unconstrained children. + +Diagnose layout failures using the following error signatures: + +* **"Vertical viewport was given unbounded height"**: Triggered when a scrollable widget (`ListView`, `GridView`) is placed inside an unconstrained vertical parent (`Column`). The parent provides infinite height, and the child attempts to expand infinitely. +* **"An InputDecorator...cannot have an unbounded width"**: Triggered when a `TextField` or `TextFormField` is placed inside an unconstrained horizontal parent (`Row`). The text field attempts to determine its width based on infinite available space. +* **"RenderFlex overflowed"**: Triggered when a child of a `Row` or `Column` requests a size larger than the parent's allocated constraints. Visually indicated by yellow and black warning stripes. +* **"Incorrect use of ParentData widget"**: Triggered when a `ParentDataWidget` is not a direct descendant of its required ancestor. (e.g., `Expanded` outside a `Flex`, `Positioned` outside a `Stack`). +* **"RenderBox was not laid out"**: A cascading side-effect error. Ignore this and look further up the stack trace for the primary constraint violation (usually an unbounded height/width error). + +## Layout Error Resolution Workflow + +Copy and use this checklist to systematically resolve layout constraint violations. + +### Task Progress +- [ ] Run the application in debug mode to capture the exact layout exception in the console. +- [ ] Identify the primary error message (ignore cascading "RenderBox was not laid out" errors). +- [ ] Apply the conditional fix based on the specific error type: + - **If "Vertical viewport was given unbounded height"**: Wrap the scrollable child (`ListView`, `GridView`) in an `Expanded` widget to consume remaining space, or wrap it in a `SizedBox` to provide an absolute height constraint. + - **If "An InputDecorator...cannot have an unbounded width"**: Wrap the `TextField` or `TextFormField` in an `Expanded` or `Flexible` widget. + - **If "RenderFlex overflowed"**: Constrain the overflowing child by wrapping it in an `Expanded` widget (to force it to fit) or a `Flexible` widget (to allow it to be smaller than the allocated space). + - **If "Incorrect use of ParentData widget"**: Move the `ParentDataWidget` to be a direct child of its required parent. Ensure `Expanded`/`Flexible` are direct children of `Row`/`Column`/`Flex`. Ensure `Positioned` is a direct child of `Stack`. +- [ ] Execute Flutter hot reload. +- [ ] Run validator -> review errors -> fix: Inspect the UI to verify the red/grey error screen or yellow/black overflow stripes are resolved. If new layout errors appear, repeat the workflow. + +## Examples + +### Fixing Unbounded Height (ListView in Column) + +**Input (Error State):** +```dart +// Throws "Vertical viewport was given unbounded height" +Column( + children: [ + const Text('Header'), + ListView( + children: const [ + ListTile(title: Text('Item 1')), + ListTile(title: Text('Item 2')), + ], + ), + ], +) +``` + +**Output (Resolved State):** +```dart +// Wrap ListView in Expanded to constrain its height to the remaining Column space +Column( + children: [ + const Text('Header'), + Expanded( + child: ListView( + children: const [ + ListTile(title: Text('Item 1')), + ListTile(title: Text('Item 2')), + ], + ), + ), + ], +) +``` + +### Fixing Unbounded Width (TextField in Row) + +**Input (Error State):** +```dart +// Throws "An InputDecorator...cannot have an unbounded width" +Row( + children: [ + const Icon(Icons.search), + TextField(), + ], +) +``` + +**Output (Resolved State):** +```dart +// Wrap TextField in Expanded to constrain its width to the remaining Row space +Row( + children: [ + const Icon(Icons.search), + Expanded( + child: TextField(), + ), + ], +) +``` + +### Fixing RenderFlex Overflow + +**Input (Error State):** +```dart +// Throws "A RenderFlex overflowed by X pixels on the right" +Row( + children: [ + const Icon(Icons.info), + const Text('This is a very long text string that will definitely overflow the available screen width and cause a RenderFlex error.'), + ], +) +``` + +**Output (Resolved State):** +```dart +// Wrap the Text widget in Expanded to force it to wrap within the available constraints +Row( + children: [ + const Icon(Icons.info), + Expanded( + child: const Text('This is a very long text string that will definitely overflow the available screen width and cause a RenderFlex error.'), + ), + ], +) +``` diff --git a/.agents/skills/flutter-implement-json-serialization/SKILL.md b/.agents/skills/flutter-implement-json-serialization/SKILL.md new file mode 100644 index 0000000..14009f4 --- /dev/null +++ b/.agents/skills/flutter-implement-json-serialization/SKILL.md @@ -0,0 +1,153 @@ +--- +name: flutter-implement-json-serialization +description: Create model classes with `fromJson` and `toJson` methods using `dart:convert`. Use when manually mapping JSON keys to class properties for simple data structures. +metadata: + model: models/gemini-3.1-pro-preview + last_modified: Tue, 21 Apr 2026 21:44:50 GMT +--- +# Serializing JSON Manually in Flutter + +## Contents +- [Core Guidelines](#core-guidelines) +- [Workflow: Implementing a Serializable Model](#workflow-implementing-a-serializable-model) +- [Workflow: Fetching and Parsing JSON](#workflow-fetching-and-parsing-json) +- [Examples](#examples) + +## Core Guidelines + +- **Import `dart:convert`**: Utilize Flutter's built-in `dart:convert` library for manual JSON encoding (`jsonEncode`) and decoding (`jsonDecode`). +- **Enforce Type Safety**: Always cast the `dynamic` result of `jsonDecode()` to the expected type, typically `Map` for objects or `List` for arrays. +- **Encapsulate Serialization Logic**: Define plain model classes containing properties corresponding to the JSON structure. Implement a `fromJson` factory constructor and a `toJson` method within the model. +- **Handle Background Parsing**: If parsing large JSON documents (execution time > 16ms), offload the parsing logic to a separate isolate using Flutter's `compute()` function to prevent UI jank. +- **Throw Exceptions on Failure**: When handling HTTP responses, throw an exception if the status code is not successful (e.g., not 200 OK or 201 Created). Do not return `null`. + +## Workflow: Implementing a Serializable Model + +Use this checklist to implement manual JSON serialization for a data model. + +**Task Progress:** +- [ ] Define the plain model class with `final` properties. +- [ ] Implement the `factory Model.fromJson(Map json)` constructor. +- [ ] Implement the `Map toJson()` method. +- [ ] Write unit tests for both serialization methods. +- [ ] Run validator -> review type mismatch errors -> fix casting logic. + +1. **Define the Model**: Create a class with properties matching the JSON keys. +2. **Implement `fromJson`**: Extract values from the `Map` and cast them to the appropriate Dart types. Use pattern matching or explicit casting. +3. **Implement `toJson`**: Return a `Map` mapping the class properties back to their JSON string keys. +4. **Validate**: Execute unit tests to ensure type safety, autocompletion, and compile-time exception handling function correctly. + +## Workflow: Fetching and Parsing JSON + +Use this conditional workflow when retrieving and parsing JSON from a network request. + +**Task Progress:** +- [ ] Execute the HTTP request. +- [ ] Validate the response status code. +- [ ] Determine parsing strategy (Synchronous vs. Isolate). +- [ ] Decode and map the JSON to the model. + +1. **Execute Request**: Use the `http` package to perform the network call. +2. **Validate Response**: + - If `response.statusCode == 200` (or 201 for POST), proceed to parsing. + - If the status code indicates failure, throw an `Exception`. +3. **Determine Parsing Strategy**: + - If parsing a **small payload** (e.g., a single object), parse synchronously on the main thread. + - If parsing a **large payload** (e.g., an array of thousands of objects), use `compute(parseFunction, response.body)` to parse in a background isolate. +4. **Decode and Map**: Pass the decoded JSON to your model's `fromJson` constructor. + +## Examples + +### High-Fidelity Model Implementation + +```dart +import 'dart:convert'; + +class User { + final int id; + final String name; + final String email; + + const User({ + required this.id, + required this.name, + required this.email, + }); + + // Factory constructor for deserialization + factory User.fromJson(Map json) { + return switch (json) { + { + 'id': int id, + 'name': String name, + 'email': String email, + } => + User( + id: id, + name: name, + email: email, + ), + _ => throw const FormatException('Failed to load User.'), + }; + } + + // Method for serialization + Map toJson() { + return { + 'id': id, + 'name': name, + 'email': email, + }; + } +} +``` + +### Synchronous Parsing (Small Payload) + +```dart +import 'dart:convert'; +import 'package:http/http.dart' as http; + +Future fetchUser(http.Client client, int userId) async { + final response = await client.get( + Uri.parse('https://api.example.com/users/$userId'), + headers: {'Accept': 'application/json'}, + ); + + if (response.statusCode == 200) { + // Decode returns dynamic, cast to Map + final Map jsonMap = jsonDecode(response.body) as Map; + return User.fromJson(jsonMap); + } else { + throw Exception('Failed to load user'); + } +} +``` + +### Background Parsing (Large Payload) + +```dart +import 'dart:convert'; +import 'package:flutter/foundation.dart'; +import 'package:http/http.dart' as http; + +// Top-level function required for compute() +List parseUsers(String responseBody) { + final parsed = (jsonDecode(responseBody) as List).cast>(); + return parsed.map((json) => User.fromJson(json)).toList(); +} + +Future> fetchUsers(http.Client client) async { + final response = await client.get( + Uri.parse('https://api.example.com/users'), + headers: {'Accept': 'application/json'}, + ); + + if (response.statusCode == 200) { + // Offload expensive parsing to a background isolate + return compute(parseUsers, response.body); + } else { + throw Exception('Failed to load users'); + } +} +``` diff --git a/.agents/skills/flutter-setup-declarative-routing/SKILL.md b/.agents/skills/flutter-setup-declarative-routing/SKILL.md new file mode 100644 index 0000000..2720311 --- /dev/null +++ b/.agents/skills/flutter-setup-declarative-routing/SKILL.md @@ -0,0 +1,255 @@ +--- +name: flutter-setup-declarative-routing +description: Configure `MaterialApp.router` using a package like `go_router` for advanced URL-based navigation. Use when developing web applications or mobile apps that require specific deep linking and browser history support. +metadata: + model: models/gemini-3.1-pro-preview + last_modified: Tue, 21 Apr 2026 21:08:03 GMT +--- +# Implementing Routing and Deep Linking + +## Contents +- [Core Concepts](#core-concepts) +- [Workflow: Initializing the Application and Router](#workflow-initializing-the-application-and-router) +- [Workflow: Configuring Platform Deep Linking](#workflow-configuring-platform-deep-linking) +- [Workflow: Implementing Nested Navigation](#workflow-implementing-nested-navigation) +- [Examples](#examples) + +## Core Concepts + +Use the `go_router` package for declarative routing in Flutter. It provides a robust API for complex routing scenarios, deep linking, and nested navigation. + +- **GoRouter**: The central configuration object defining the application's route tree. +- **GoRoute**: A standard route mapping a URL path to a Flutter screen. +- **ShellRoute / StatefulShellRoute**: Wraps child routes in a persistent UI shell (e.g., a `BottomNavigationBar`). `StatefulShellRoute` maintains the state of parallel navigation branches. +- **Path URL Strategy**: Removes the default `#` fragment from web URLs, essential for clean deep linking across platforms. + +## Workflow: Initializing the Application and Router + +Follow this workflow to bootstrap a new Flutter application with `go_router` and configure the root routing mechanism. + +### Task Progress +- [ ] Create the Flutter application. +- [ ] Add the `go_router` dependency. +- [ ] Configure the URL strategy for web/deep linking. +- [ ] Implement the `GoRouter` configuration. +- [ ] Bind the router to `MaterialApp.router`. + +### 1. Scaffold the Application +Run the following commands to create the app and add the required routing package: +```bash +flutter create +cd +flutter pub add go_router +``` + +### 2. Configure the Router +Define a top-level `GoRouter` instance. Handle authentication or state-based routing using the `redirect` parameter. + +```dart +import 'package:flutter/material.dart'; +import 'package:go_router/go_router.dart'; +import 'package:flutter_web_plugins/url_strategy.dart'; + +void main() { + // Use path URL strategy to remove the '#' from web URLs + usePathUrlStrategy(); + runApp(const MyApp()); +} + +final GoRouter _router = GoRouter( + initialLocation: '/', + routes: [ + GoRoute( + path: '/', + builder: (context, state) => const HomeScreen(), + routes: [ + GoRoute( + path: 'details/:id', + builder: (context, state) => DetailsScreen(id: state.pathParameters['id']!), + ), + ], + ), + ], + errorBuilder: (context, state) => ErrorScreen(error: state.error), +); + +class MyApp extends StatelessWidget { + const MyApp({super.key}); + + @override + Widget build(BuildContext context) { + return MaterialApp.router( + routerConfig: _router, + title: 'Routing App', + ); + } +} +``` + +## Workflow: Configuring Platform Deep Linking + +Configure the native platforms to intercept specific URLs and route them into the Flutter application. + +### Task Progress +- [ ] Determine target platforms (iOS, Android, or both). +- [ ] Apply conditional configuration for Android (Manifest + Asset Links). +- [ ] Apply conditional configuration for iOS (Plist + Entitlements + AASA). +- [ ] Run validator -> review errors -> fix. + +### If configuring for Android: +1. **Modify `AndroidManifest.xml`**: Add the intent filter inside the `` tag for `.MainActivity`. +```xml + + + + + + + +``` +2. **Host `assetlinks.json`**: Serve the following JSON at `https://yourdomain.com/.well-known/assetlinks.json`. +```json +[{ + "relation": ["delegate_permission/common.handle_all_urls"], + "target": { + "namespace": "android_app", + "package_name": "com.yourcompany.yourapp", + "sha256_cert_fingerprints": ["YOUR_SHA256_FINGERPRINT"] + } +}] +``` + +### If configuring for iOS: +1. **Modify `Info.plist`**: Opt-in to Flutter's default deep link handler. +*Note: If using a third-party deep linking plugin (e.g., `app_links`), set this to `NO` to prevent conflicts.* +```xml +FlutterDeepLinkingEnabled + +``` +2. **Modify `Runner.entitlements`**: Add the associated domain. +```xml +com.apple.developer.associated-domains + + applinks:yourdomain.com + +``` +3. **Host `apple-app-site-association`**: Serve the following JSON (without a `.json` extension) at `https://yourdomain.com/.well-known/apple-app-site-association`. +```json +{ + "applinks": { + "apps": [], + "details": [{ + "appIDs": ["TEAM_ID.com.yourcompany.yourapp"], + "paths": ["*"], + "components": [{"/": "/*"}] + }] + } +} +``` + +### Validation Loop +Run validator -> review errors -> fix. +- **Android**: Test using ADB. + ```bash + adb shell 'am start -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d "https://yourdomain.com/details/123"' com.yourcompany.yourapp + ``` +- **iOS**: Test using `xcrun` on a booted simulator. + ```bash + xcrun simctl openurl booted https://yourdomain.com/details/123 + ``` + +## Workflow: Implementing Nested Navigation + +Use `StatefulShellRoute` to implement persistent UI shells (like a bottom navigation bar) that maintain the state of their child routes. + +### Task Progress +- [ ] Define `StatefulShellRoute.indexedStack` in the `GoRouter` configuration. +- [ ] Create `StatefulShellBranch` instances for each navigation tab. +- [ ] Implement the shell widget using `StatefulNavigationShell`. + +```dart +final GoRouter _router = GoRouter( + initialLocation: '/home', + routes: [ + StatefulShellRoute.indexedStack( + builder: (context, state, navigationShell) { + return ScaffoldWithNavBar(navigationShell: navigationShell); + }, + branches: [ + StatefulShellBranch( + routes: [ + GoRoute( + path: '/home', + builder: (context, state) => const HomeScreen(), + ), + ], + ), + StatefulShellBranch( + routes: [ + GoRoute( + path: '/settings', + builder: (context, state) => const SettingsScreen(), + ), + ], + ), + ], + ), + ], +); +``` + +## Examples + +### High-Fidelity Shell Widget Implementation +Implement the UI shell that consumes the `StatefulNavigationShell` to handle branch switching. + +```dart +class ScaffoldWithNavBar extends StatelessWidget { + const ScaffoldWithNavBar({ + required this.navigationShell, + super.key, + }); + + final StatefulNavigationShell navigationShell; + + void _goBranch(int index) { + navigationShell.goBranch( + index, + // Support navigating to the initial location when tapping the active tab. + initialLocation: index == navigationShell.currentIndex, + ); + } + + @override + Widget build(BuildContext context) { + return Scaffold( + body: navigationShell, + bottomNavigationBar: NavigationBar( + selectedIndex: navigationShell.currentIndex, + onDestinationSelected: _goBranch, + destinations: const [ + NavigationDestination(icon: Icon(Icons.home), label: 'Home'), + NavigationDestination(icon: Icon(Icons.settings), label: 'Settings'), + ], + ), + ); + } +} +``` + +### Programmatic Navigation +Use the `context.go()` and `context.push()` extension methods provided by `go_router`. + +```dart +// Replaces the current route stack with the target route (Declarative) +context.go('/details/123'); + +// Pushes the target route onto the existing stack (Imperative) +context.push('/details/123'); + +// Navigates using a named route and path parameters +context.goNamed('details', pathParameters: {'id': '123'}); + +// Pops the current route +context.pop(); +``` diff --git a/.agents/skills/flutter-setup-localization/SKILL.md b/.agents/skills/flutter-setup-localization/SKILL.md new file mode 100644 index 0000000..d3dd459 --- /dev/null +++ b/.agents/skills/flutter-setup-localization/SKILL.md @@ -0,0 +1,210 @@ +--- +name: flutter-setup-localization +description: Add `flutter_localizations` and `intl` dependencies, enable "generate true" in `pubspec.yaml`, and create an `l10n.yaml` configuration file. Use when initializing localization support for a new Flutter project. +metadata: + model: models/gemini-3.1-pro-preview + last_modified: Tue, 21 Apr 2026 21:27:35 GMT +--- +# Internationalizing Flutter Applications + +## Contents +- [Core Concepts](#core-concepts) +- [Setup Workflow](#setup-workflow) +- [Implementation Workflow](#implementation-workflow) +- [Advanced Formatting](#advanced-formatting) +- [Examples](#examples) + +## Core Concepts +Flutter handles internationalization (i18n) and localization (l10n) via the `flutter_localizations` and `intl` packages. The standard approach uses App Resource Bundle (`.arb`) files to define localized strings, which are then compiled into a generated `AppLocalizations` class for type-safe access within the widget tree. + +## Setup Workflow + +Copy and track this checklist when initializing internationalization in a Flutter project: + +- [ ] **Task Progress** + - [ ] 1. Add dependencies to `pubspec.yaml`. + - [ ] 2. Enable the `generate` flag. + - [ ] 3. Create the `l10n.yaml` configuration file. + - [ ] 4. Configure `MaterialApp` or `CupertinoApp`. + +### 1. Add Dependencies +Add the required localization packages to the project. Execute the following commands in the terminal: +```bash +flutter pub add flutter_localizations --sdk=flutter +flutter pub add intl:any +``` + +Verify your `pubspec.yaml` includes the following under `dependencies`: +```yaml +dependencies: + flutter: + sdk: flutter + flutter_localizations: + sdk: flutter + intl: any +``` + +### 2. Enable Code Generation +Open `pubspec.yaml` and enable the `generate` flag within the `flutter` section to automate localization tasks: +```yaml +flutter: + generate: true +``` + +### 3. Create Configuration File +Create a new file named `l10n.yaml` in the root directory of the Flutter project. Define the input directory, template file, and output file: +```yaml +arb-dir: lib/l10n +template-arb-file: app_en.arb +output-localization-file: app_localizations.dart +synthetic-package: true +``` + +### 4. Configure the App Entry Point +Import the generated localizations and the `flutter_localizations` library in your `main.dart`. Inject the delegates and supported locales into your `MaterialApp` or `CupertinoApp`. + +```dart +import 'package:flutter_localizations/flutter_localizations.dart'; +import 'package:flutter_gen/gen_l10n/app_localizations.dart'; // Adjust path if synthetic-package is false + +// ... inside build method +return MaterialApp( + localizationsDelegates: const [ + AppLocalizations.delegate, + GlobalMaterialLocalizations.delegate, + GlobalWidgetsLocalizations.delegate, + GlobalCupertinoLocalizations.delegate, + ], + supportedLocales: const [ + Locale('en'), // English + Locale('es'), // Spanish + ], + home: const MyHomePage(), +); +``` + +## Implementation Workflow + +Follow this workflow when adding or modifying localized content. + +### 1. Define ARB Files +* **If creating NEW content:** Add the base string to the template file (`lib/l10n/app_en.arb`). Include a description for context. +* **If EDITING existing content:** Locate the key in all supported `.arb` files and update the values. + +```json +{ + "helloWorld": "Hello World!", + "@helloWorld": { + "description": "The conventional newborn programmer greeting" + } +} +``` + +Create corresponding files for other locales (e.g., `app_es.arb`): +```json +{ + "helloWorld": "¡Hola Mundo!" +} +``` + +### 2. Generate Localization Classes +Run the following command to trigger code generation: +```bash +flutter pub get +``` +*Feedback Loop:* Run validator -> review terminal output for ARB syntax errors -> fix missing commas or mismatched placeholders -> re-run `flutter pub get`. + +### 3. Consume Localized Strings +Access the localized strings in your widget tree using `AppLocalizations.of(context)`. Ensure the widget calling this is a descendant of `MaterialApp`. + +```dart +Text(AppLocalizations.of(context)!.helloWorld) +``` + +## Advanced Formatting + +Use placeholders for dynamic data, plurals, and conditional selects. + +### Placeholders +Define parameters within curly braces and specify their type in the metadata object. +```json +"hello": "Hello {userName}", +"@hello": { + "description": "A message with a single parameter", + "placeholders": { + "userName": { + "type": "String", + "example": "Bob" + } + } +} +``` + +### Plurals +Use the `plural` syntax to handle quantity-based string variations. The `other` case is mandatory. +```json +"nWombats": "{count, plural, =0{no wombats} =1{1 wombat} other{{count} wombats}}", +"@nWombats": { + "description": "A plural message", + "placeholders": { + "count": { + "type": "num", + "format": "compact" + } + } +} +``` + +### Selects +Use the `select` syntax for conditional strings, such as gendered text. +```json +"pronoun": "{gender, select, male{he} female{she} other{they}}", +"@pronoun": { + "description": "A gendered message", + "placeholders": { + "gender": { + "type": "String" + } + } +} +``` + +## Examples + +### Complete `l10n.yaml` +```yaml +arb-dir: lib/l10n +template-arb-file: app_en.arb +output-localization-file: app_localizations.dart +synthetic-package: true +use-escaping: true +``` + +### Complete Widget Implementation +```dart +import 'package:flutter/material.dart'; +import 'package:flutter_gen/gen_l10n/app_localizations.dart'; + +class GreetingWidget extends StatelessWidget { + final String userName; + final int notificationCount; + + const GreetingWidget({ + super.key, + required this.userName, + required this.notificationCount, + }); + + @override + Widget build(BuildContext context) { + final l10n = AppLocalizations.of(context)!; + + return Column( + children: [ + Text(l10n.hello(userName)), + Text(l10n.nWombats(notificationCount)), + ], + ); + } +} +``` diff --git a/.agents/skills/flutter-use-http-package/SKILL.md b/.agents/skills/flutter-use-http-package/SKILL.md new file mode 100644 index 0000000..bb60468 --- /dev/null +++ b/.agents/skills/flutter-use-http-package/SKILL.md @@ -0,0 +1,174 @@ +--- +name: flutter-use-http-package +description: Use the `http` package to execute GET, POST, PUT, or DELETE requests. Use when you need to fetch from or send data to a REST API. +metadata: + model: models/gemini-3.1-pro-preview + last_modified: Tue, 21 Apr 2026 21:36:42 GMT +--- +# Implementing Flutter Networking + +## Contents +- [Configuration & Permissions](#configuration--permissions) +- [Request Execution & Response Handling](#request-execution--response-handling) +- [Background Parsing](#background-parsing) +- [Workflow: Executing Network Operations](#workflow-executing-network-operations) +- [Examples](#examples) + +## Configuration & Permissions + +Configure the environment and platform-specific permissions required for network access. + +1. Add the `http` package dependency via the terminal: + ```bash + flutter pub add http + ``` +2. Import the package in your Dart files: + ```dart + import 'package:http/http.dart' as http; + ``` +3. Configure Android permissions by adding the Internet permission to `android/app/src/main/AndroidManifest.xml`: + ```xml + + ``` +4. Configure macOS entitlements by adding the network client key to both `macos/Runner/DebugProfile.entitlements` and `macos/Runner/Release.entitlements`: + ```xml + com.apple.security.network.client + + ``` + +## Request Execution & Response Handling + +Execute HTTP operations and map responses to strongly typed Dart objects. + +* **URIs:** Always parse URL strings using `Uri.parse('your_url')`. +* **Headers:** Inject authorization and content-type headers via the `headers` parameter map. Use `HttpHeaders.authorizationHeader` for auth tokens. +* **Payloads:** For POST and PUT requests, encode the body using `jsonEncode()` from `dart:convert`. +* **Status Validation:** Evaluate `response.statusCode`. Treat `200 OK` (GET/PUT/DELETE) and `201 CREATED` (POST) as success. +* **Error Handling:** Throw explicit exceptions for non-success status codes. Never return `null` on failure, as this prevents `FutureBuilder` from triggering its error state and causes infinite loading indicators. +* **Deserialization:** Parse the raw string using `jsonDecode(response.body)` and map it to a custom Dart object using a factory constructor (e.g., `fromJson`). + +## Background Parsing + +Offload expensive JSON parsing to a separate Isolate to prevent UI jank (frame drops). + +* Import `package:flutter/foundation.dart`. +* Use the `compute()` function to run the parsing logic in a background isolate. +* Ensure the parsing function passed to `compute()` is a top-level function or a static method, as closures or instance methods cannot be passed across isolates. + +## Workflow: Executing Network Operations + +Use the following checklist to implement and validate network operations. + +**Task Progress:** +- [ ] 1. Define the strongly typed Dart model with a `fromJson` factory constructor. +- [ ] 2. Implement the network request method returning a `Future`. +- [ ] 3. Apply conditional logic based on the operation type: + - **If fetching data (GET):** Append query parameters to the URI. + - **If mutating data (POST/PUT):** Set `'Content-Type': 'application/json; charset=UTF-8'` and attach the `jsonEncode` body. + - **If deleting data (DELETE):** Return an empty model instance on success (`200 OK`). +- [ ] 4. Validate the `statusCode` and throw an `Exception` on failure. +- [ ] 5. Integrate the `Future` into the UI using `FutureBuilder`. +- [ ] 6. Handle `snapshot.hasData`, `snapshot.hasError`, and default to a `CircularProgressIndicator`. +- [ ] 7. **Feedback Loop:** Run the app -> trigger the network request -> review console for unhandled exceptions -> fix parsing or permission errors. + +## Examples + +### High-Fidelity Implementation: Fetching and Parsing in the Background + +```dart +import 'dart:async'; +import 'dart:convert'; +import 'dart:io'; +import 'package:flutter/foundation.dart'; +import 'package:flutter/material.dart'; +import 'package:http/http.dart' as http; + +// 1. Top-level parsing function for Isolate +List parsePhotos(String responseBody) { + final parsed = (jsonDecode(responseBody) as List) + .cast>(); + return parsed.map(Photo.fromJson).toList(); +} + +// 2. Network execution with background parsing +Future> fetchPhotos() async { + final response = await http.get( + Uri.parse('https://jsonplaceholder.typicode.com/photos'), + headers: { + HttpHeaders.authorizationHeader: 'Bearer your_token_here', + HttpHeaders.acceptHeader: 'application/json', + }, + ); + + if (response.statusCode == 200) { + // Offload heavy parsing to a background isolate + return compute(parsePhotos, response.body); + } else { + throw Exception('Failed to load photos. Status: ${response.statusCode}'); + } +} + +// 3. Strongly typed model +class Photo { + final int id; + final String title; + final String thumbnailUrl; + + const Photo({ + required this.id, + required this.title, + required this.thumbnailUrl, + }); + + factory Photo.fromJson(Map json) { + return Photo( + id: json['id'] as int, + title: json['title'] as String, + thumbnailUrl: json['thumbnailUrl'] as String, + ); + } +} + +// 4. UI Integration +class PhotoGallery extends StatefulWidget { + const PhotoGallery({super.key}); + + @override + State createState() => _PhotoGalleryState(); +} + +class _PhotoGalleryState extends State { + late Future> _futurePhotos; + + @override + void initState() { + super.initState(); + // Initialize Future once to prevent re-fetching on rebuilds + _futurePhotos = fetchPhotos(); + } + + @override + Widget build(BuildContext context) { + return FutureBuilder>( + future: _futurePhotos, + builder: (context, snapshot) { + if (snapshot.hasData) { + final photos = snapshot.data!; + return ListView.builder( + itemCount: photos.length, + itemBuilder: (context, index) => ListTile( + leading: Image.network(photos[index].thumbnailUrl), + title: Text(photos[index].title), + ), + ); + } else if (snapshot.hasError) { + return Center(child: Text('Error: ${snapshot.error}')); + } + + // Default loading state + return const Center(child: CircularProgressIndicator()); + }, + ); + } +} +``` diff --git a/.gitignore b/.gitignore index cdcd54c..8bf0430 100644 --- a/.gitignore +++ b/.gitignore @@ -53,4 +53,5 @@ app.*.map.json macos/Flutter/GeneratedPluginRegistrant.swift .claude -CLAUDE.md \ No newline at end of file +CLAUDE.md +data/ \ No newline at end of file diff --git a/android/app/build.gradle.kts b/android/app/build.gradle.kts index ec3502f..ff48d95 100644 --- a/android/app/build.gradle.kts +++ b/android/app/build.gradle.kts @@ -1,5 +1,6 @@ import java.util.Properties import java.io.FileInputStream +import org.jetbrains.kotlin.gradle.dsl.JvmTarget plugins { id("com.android.application") @@ -14,6 +15,12 @@ if (keystorePropertiesFile.exists()) { keystoreProperties.load(FileInputStream(keystorePropertiesFile)) } +kotlin { + compilerOptions { + jvmTarget.set(JvmTarget.JVM_11) + } +} + android { namespace = "top.merack.time_machine" compileSdk = flutter.compileSdkVersion @@ -25,9 +32,9 @@ android { targetCompatibility = JavaVersion.VERSION_11 } - kotlinOptions { - jvmTarget = JavaVersion.VERSION_11.toString() - } +// kotlinOptions { +// jvmTarget = JavaVersion.VERSION_11.toString() +// } defaultConfig { // TODO: Specify your own unique Application ID (https://developer.android.com/studio/build/application-id.html). @@ -58,13 +65,14 @@ android { // signingConfig = signingConfigs.getByName("debug") signingConfig = signingConfigs.getByName("release") } + debug { applicationIdSuffix = ".debug" } } } dependencies { // 添加Desugaring依赖 - coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.4") + coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5") } flutter { diff --git a/android/app/src/main/AndroidManifest.xml b/android/app/src/main/AndroidManifest.xml index 635f642..2deee92 100644 --- a/android/app/src/main/AndroidManifest.xml +++ b/android/app/src/main/AndroidManifest.xml @@ -8,9 +8,13 @@ - - + + + + + + {uri, title} | null + * - playRingtone(uri: String) -> Boolean + * - stopRingtone() + * - getRingtoneTitle(uri: String) -> String? + * + * 回调(Dart 侧 setMethodCallHandler): + * - onRingtoneCompleted -> 单次铃声播放自然结束 + */ +class RingtoneChannel( + private val activity: MainActivity, + flutterEngine: FlutterEngine, +) : MethodChannel.MethodCallHandler { + + companion object { + private const val CHANNEL = "top.merack.time_machine/ringtone" + private const val REQ_PICK_RINGTONE = 1042 + } + + private val channel = + MethodChannel(flutterEngine.dartExecutor.binaryMessenger, CHANNEL) + + private var pendingResult: MethodChannel.Result? = null + private var currentPlayer: MediaPlayer? = null + + init { + channel.setMethodCallHandler(this) + } + + override fun onMethodCall( + call: MethodCall, + result: MethodChannel.Result + ) { + when (call.method) { + "pickRingtone" -> handlePick(call, result) + "playRingtone" -> handlePlay(call, result) + + "stopRingtone" -> { + stopCurrent(notifyCompleted = false) + result.success(null) + } + + "getRingtoneTitle" -> handleGetTitle(call, result) + + else -> result.notImplemented() + } + } + + private fun handlePick( + call: MethodCall, + result: MethodChannel.Result + ) { + if (pendingResult != null) { + result.error( + "BUSY", + "已有铃声选择请求在进行中", + null + ) + return + } + + // 保存给flutter侧返回结果的对象, 因为在此函数中不处理返回, 只是通知系统打开铃声选择 + // 用户选完铃声后给flutter的返回处理在onActivityResult中 + pendingResult = result + + val intent = + Intent(RingtoneManager.ACTION_RINGTONE_PICKER).apply { + putExtra( + RingtoneManager.EXTRA_RINGTONE_TYPE, + RingtoneManager.TYPE_NOTIFICATION or + RingtoneManager.TYPE_RINGTONE + ) + + putExtra( + RingtoneManager.EXTRA_RINGTONE_TITLE, + "选择提示音" + ) + + putExtra( + RingtoneManager.EXTRA_RINGTONE_SHOW_DEFAULT, + true + ) + + putExtra( + RingtoneManager.EXTRA_RINGTONE_SHOW_SILENT, + false + ) + + val current = + call.argument("currentUri") + + if (!current.isNullOrEmpty()) { + putExtra( + RingtoneManager.EXTRA_RINGTONE_EXISTING_URI, + current.toUri() + ) + } + } + + try { + activity.startActivityForResult( + intent, + REQ_PICK_RINGTONE + ) + } catch (e: Exception) { + pendingResult = null + result.error( + "PICK_FAILED", + e.message, + null + ) + } + } + + private fun handlePlay( + call: MethodCall, + result: MethodChannel.Result + ) { + val uriStr = call.argument("uri") + + if (uriStr.isNullOrEmpty()) { + result.success(false) + return + } + + try { + stopCurrent(notifyCompleted = false) + + val player = MediaPlayer() + currentPlayer = player + player.apply { + setAudioAttributes( + AudioAttributes.Builder() + .setUsage(AudioAttributes.USAGE_MEDIA) + .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC) + .build() + ) + isLooping = false + setDataSource(activity, uriStr.toUri()) + setOnCompletionListener { mp -> + // 自然播放完成: 释放并通知 Dart 侧 + if (currentPlayer === mp) { + stopCurrent(notifyCompleted = true) + } +// if (currentPlayer === it) { +// try { it.release() } catch (_: Exception) {} +// currentPlayer = null +// } +// channel.invokeMethod("onRingtoneCompleted", null) + } + setOnErrorListener { mp, _, _ -> + if (currentPlayer === mp) { + try { mp.release() } catch (_: Exception) {} + currentPlayer = null + } + true + } + prepare() + start() + } +// currentPlayer = player + result.success(true) + + } catch (e: Exception) { + try { + currentPlayer?.release() + } catch (_: Exception) {} + currentPlayer = null + result.error( + "PLAY_FAILED", + e.message, + null + ) + } + } + + private fun handleGetTitle( + call: MethodCall, + result: MethodChannel.Result + ) { + val uriStr = + call.argument("uri") + + if (uriStr.isNullOrEmpty()) { + result.success(null) + return + } + + try { + val ringtone = + RingtoneManager.getRingtone( + activity, + uriStr.toUri() + ) + + result.success( + ringtone?.getTitle(activity) + ) + + } catch (_: Exception) { + result.success(null) + } + } + + private fun stopCurrent(notifyCompleted: Boolean) { + val player = currentPlayer ?: return + currentPlayer = null + try { + if (player.isPlaying) { + player.stop() + } + } catch (_: Exception) { + } + try { + player.release() + } catch (_: Exception) { + } + // 正常播放完毕 + if (notifyCompleted) { + channel.invokeMethod("onRingtoneCompleted", null) + } + } + + fun onActivityResult( + requestCode: Int, + resultCode: Int, + data: Intent? + ): Boolean { + if (requestCode != REQ_PICK_RINGTONE) { + return false + } + + val result = pendingResult ?: return true + pendingResult = null + + // 处理用户取消了选择的情况 + if (resultCode != Activity.RESULT_OK) { + result.success(null) + return true + } + + val uri: Uri? = + if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) { + data?.getParcelableExtra( + RingtoneManager.EXTRA_RINGTONE_PICKED_URI, + Uri::class.java + ) + } else { // 处理兼容Android 13以下系统 + @Suppress("DEPRECATION") + data?.getParcelableExtra( + RingtoneManager.EXTRA_RINGTONE_PICKED_URI + ) + } + + if (uri == null) { + result.success(null) + return true + } + + val title = try { + RingtoneManager + .getRingtone(activity, uri) + ?.getTitle(activity) + } catch (_: Exception) { + null + } ?: "系统铃声" + + result.success( + mapOf( + "uri" to uri.toString(), + "title" to title + ) + ) + + return true + } + + fun dispose() { + stopCurrent(notifyCompleted = false) + channel.setMethodCallHandler(null) + } +} diff --git a/android/gradle.properties b/android/gradle.properties index f018a61..a562c50 100644 --- a/android/gradle.properties +++ b/android/gradle.properties @@ -1,3 +1,10 @@ org.gradle.jvmargs=-Xmx8G -XX:MaxMetaspaceSize=4G -XX:ReservedCodeCacheSize=512m -XX:+HeapDumpOnOutOfMemoryError android.useAndroidX=true android.enableJetifier=true +#android.newDsl=false +#android.builtInKotlin=false + +# This builtInKotlin flag was added automatically by Flutter migrator +android.builtInKotlin=false +# This newDsl flag was added automatically by Flutter migrator +android.newDsl=false diff --git a/android/gradle/wrapper/gradle-wrapper.properties b/android/gradle/wrapper/gradle-wrapper.properties index ac3b479..02767eb 100644 --- a/android/gradle/wrapper/gradle-wrapper.properties +++ b/android/gradle/wrapper/gradle-wrapper.properties @@ -2,4 +2,4 @@ distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists zipStoreBase=GRADLE_USER_HOME zipStorePath=wrapper/dists -distributionUrl=https\://services.gradle.org/distributions/gradle-8.12-all.zip +distributionUrl=https\://services.gradle.org/distributions/gradle-8.13-all.zip diff --git a/android/settings.gradle.kts b/android/settings.gradle.kts index 57fc45f..8fb1a50 100644 --- a/android/settings.gradle.kts +++ b/android/settings.gradle.kts @@ -22,8 +22,8 @@ pluginManagement { plugins { id("dev.flutter.flutter-plugin-loader") version "1.0.0" - id("com.android.application") version "8.7.3" apply false - id("org.jetbrains.kotlin.android") version "2.1.0" apply false + id("com.android.application") version "8.13.2" apply false + id("org.jetbrains.kotlin.android") version "2.3.0" apply false } include(":app") diff --git a/lib/config/storage_keys.dart b/lib/config/storage_keys.dart index 6c0acb0..e37881c 100644 --- a/lib/config/storage_keys.dart +++ b/lib/config/storage_keys.dart @@ -46,4 +46,55 @@ class StorageKeys { static const int defaultPomodoroShortBreakMinutes = 5; static const int defaultPomodoroLongBreakMinutes = 20; static const int defaultPomodoroLongBreakInterval = 4; + + // ===== 提示音事件 ===== + // eventId 列表 + static const String soundEventMicroBreakStart = 'microBreakStart'; + static const String soundEventMicroBreakComplete = 'microBreakComplete'; + static const String soundEventFocusComplete = 'focusComplete'; + static const String soundEventBreakComplete = 'breakComplete'; + + static const List soundEventIds = [ + soundEventMicroBreakStart, + soundEventMicroBreakComplete, + soundEventFocusComplete, + soundEventBreakComplete, + ]; + + // 提示音类型常量 + static const String soundTypeBuiltin = 'builtin'; + static const String soundTypeSystem = 'system'; + static const String soundTypeCustom = 'custom'; + + // 软件内置音效资源路径(供选择对话框使用) + static const Map builtinSounds = { + 'audio/drop.mp3': 'drop', + 'audio/ding.mp3': 'ding', + 'audio/wakeup.mp3': 'wakeup', + 'audio/alarm-bell.mp3': 'bell', + 'audio/alarm-kitchen.mp3': 'kitchen', + 'audio/alarm-wood.mp3': 'wood', + }; + + // 各事件默认 builtin 资源路径 + static const Map defaultEventSounds = { + soundEventMicroBreakStart: 'audio/drop.mp3', + soundEventMicroBreakComplete: 'audio/ding.mp3', + soundEventFocusComplete: 'audio/wakeup.mp3', + soundEventBreakComplete: 'audio/alarm-wood.mp3', + }; + + // 事件展示名 + static const Map eventDisplayNames = { + soundEventMicroBreakStart: '微休息开始', + soundEventMicroBreakComplete: '微休息结束', + soundEventFocusComplete: '专注完成', + soundEventBreakComplete: '大休息/长休息结束', + }; + + // 提示音 MMKV 键辅助方法 + static String soundTypeKey(String eventId) => 'sound_${eventId}_type'; + static String soundValueKey(String eventId) => 'sound_${eventId}_value'; + static String soundDisplayNameKey(String eventId) => 'sound_${eventId}_display_name'; + } diff --git a/lib/database/backup_restore_db_service.dart b/lib/database/backup_restore_db_service.dart index 51e2b43..21aa294 100644 --- a/lib/database/backup_restore_db_service.dart +++ b/lib/database/backup_restore_db_service.dart @@ -177,7 +177,7 @@ class BackupRestoreDBService { /// 将MMKV设置数据转移到settings表 Future _transferMMKVToSettings(Database backupDB) async { final settingsToBackup = []; - + // 定义需要备份的设置键和类型 final settingsMap = { StorageKeys.focusTimeMinutes: 'int', @@ -196,6 +196,12 @@ class BackupRestoreDBService { StorageKeys.pomodoroLongBreakMinutes: 'int', StorageKeys.pomodoroLongBreakInterval: 'int', }; + + // 加入提示音事件的 type/value 键 + for (final eventId in StorageKeys.soundEventIds) { + settingsMap[StorageKeys.soundTypeKey(eventId)] = 'string'; + settingsMap[StorageKeys.soundValueKey(eventId)] = 'string'; + } for (final entry in settingsMap.entries) { final key = entry.key; diff --git a/lib/main.dart b/lib/main.dart index 28d7a04..5dae6d8 100644 --- a/lib/main.dart +++ b/lib/main.dart @@ -9,6 +9,9 @@ import 'package:time_machine/route/route_page.dart'; import 'package:time_machine/service/app_storage_service.dart'; import 'package:time_machine/service/database_service.dart'; import 'package:time_machine/service/background_timer_service.dart'; +import 'package:time_machine/service/permission_service.dart'; +import 'package:time_machine/service/custom_sound_storage_service.dart'; +import 'package:time_machine/service/ringtone_picker_service.dart'; import 'package:time_machine/theme/theme_controller.dart'; import 'package:time_machine/theme/app_themes.dart'; @@ -74,15 +77,52 @@ Future initServices() async { Get.log('BackgroundTimerService初始化失败: $e'); } + // 权限管理服务 + await Get.putAsync(() => PermissionService().init()); + + // 自定义提示音文件管理 + await Get.putAsync(() => CustomSoundStorageService().init()); + + // 系统铃声 MethodChannel 封装 + Get.put(RingtonePickerService()); + // 初始化主题控制器 Get.put(ThemeController()); Get.log('All services started...'); } -class MyApp extends StatelessWidget { +class MyApp extends StatefulWidget { const MyApp({super.key}); + @override + State createState() => _MyAppState(); +} + +class _MyAppState extends State with WidgetsBindingObserver { + @override + void initState() { + super.initState(); + WidgetsBinding.instance.addObserver(this); + } + + @override + void dispose() { + WidgetsBinding.instance.removeObserver(this); + super.dispose(); + } + + @override + void didChangeAppLifecycleState(AppLifecycleState state) { + super.didChangeAppLifecycleState(state); + if (state == AppLifecycleState.resumed) { + // 用户从系统设置页返回时刷新权限状态 + if (Get.isRegistered()) { + Get.find().refreshAll(); + } + } + } + @override Widget build(BuildContext context) { final themeController = Get.find(); diff --git a/lib/page/home/controller.dart b/lib/page/home/controller.dart index a6aa8ab..74d01ec 100644 --- a/lib/page/home/controller.dart +++ b/lib/page/home/controller.dart @@ -7,6 +7,7 @@ import 'package:mmkv/mmkv.dart'; import '../../dao/focus_session_dao.dart'; import '../../model/focus_session_model.dart'; import '../../service/app_storage_service.dart'; +import '../../service/ringtone_picker_service.dart'; import '../../config/storage_keys.dart'; import 'state.dart'; @@ -280,7 +281,14 @@ class HomeController extends GetxController { // } /// 暂停计时器 (new) - void _pauseTimer() { + Future _pauseTimer() async { + try { + if (_audioPlayer.state == PlayerState.playing) { + await _audioPlayer.stop(); + } + } catch (e) { + Get.log('停止播放失败: $e'); + } // 一同暂停专注和微休息 _backgroundService.invoke("stop_timer"); state.previousStatus.value = state.timerStatus.value; @@ -390,7 +398,7 @@ class HomeController extends GetxController { void _handleMicroBreakStart() { Get.log("微休息开始"); // 播放微休息开始音效 - _playAudio('audio/drop.mp3'); + _playAudio(StorageKeys.soundEventMicroBreakStart); // 进入微休息状态 state.timerStatus.value = TimerStatus.microBreak; @@ -409,7 +417,7 @@ class HomeController extends GetxController { Get.log("微休息结束"); // 播放微休息结束音效 - _playAudio('audio/ding.mp3'); + _playAudio(StorageKeys.soundEventMicroBreakComplete); // 更新状态 state.timerStatus.value = TimerStatus.focus; @@ -546,7 +554,7 @@ class HomeController extends GetxController { _recordFocusSession(); // 播放专注完成音效 - _playAudio('audio/wakeup.mp3'); + _playAudio(StorageKeys.soundEventFocusComplete); // 增加完成周期数（随机提示音模式） state.completedRandomCycles.value++; @@ -573,7 +581,7 @@ class HomeController extends GetxController { void _completeBigBreak() { // 播放大休息结束音效 if (state.bigBreakTimeSeconds.value != 0) { - _playAudio('audio/alarm-wood.mp3'); + _playAudio(StorageKeys.soundEventBreakComplete); } if (state.autoStartNextFocus.value) { @@ -592,7 +600,7 @@ class HomeController extends GetxController { _recordFocusSession(); // 播放专注完成音效 - _playAudio('audio/wakeup.mp3'); + _playAudio(StorageKeys.soundEventFocusComplete); // 增加完成周期数和番茄计数 state.completedPomodoroCycles.value++; @@ -625,7 +633,7 @@ class HomeController extends GetxController { /// 完成番茄短休息 void _completeShortBreak() { - _playAudio('audio/alarm-wood.mp3'); + _playAudio(StorageKeys.soundEventBreakComplete); if (state.autoStartNextFocus.value) { resetTimer(); @@ -693,9 +701,16 @@ class HomeController extends GetxController { } } - /// 播放按钮音效 - void _playButtonSound() { - _playAudio('audio/button.wav'); + /// 播放按钮音效(写死, 不参与用户配置) + void _playButtonSound() async { + try { + if (_audioPlayer.state == PlayerState.playing) { + await _audioPlayer.stop(); + } + await _audioPlayer.play(AssetSource('audio/button.wav')); + } catch (e) { + Get.log('播放按钮音失败: $e'); + } } /// 切换禅模式 @@ -718,16 +733,46 @@ class HomeController extends GetxController { } /// 播放音频 - void _playAudio(String assetPath) async { + /// [eventId] 来自 StorageKeys.soundEventIds + void _playAudio(String eventId) async { try { // 当新的播放请求来临时打断之前的播放 - // 目前还不可以处理按钮的快速点击, 仅是处理阶段结束音乐播放时按下按钮的情况 if (_audioPlayer.state == PlayerState.playing) { - _audioPlayer.stop(); + await _audioPlayer.stop(); + } + + // 同时停掉可能在播的系统铃声 + try { + Get.find().stopSystemRingtone(); + } catch (_) {} + + final type = _storage.decodeString(StorageKeys.soundTypeKey(eventId)) ?? + StorageKeys.soundTypeBuiltin; + final value = _storage.decodeString(StorageKeys.soundValueKey(eventId)) ?? + StorageKeys.defaultEventSounds[eventId]!; + + switch (type) { + case StorageKeys.soundTypeSystem: + final ringtone = Get.find(); + final ok = await ringtone.playSystemRingtone(value); + if (!ok) { + // 系统铃声播放失败回退到默认 builtin + await _audioPlayer.play(AssetSource(StorageKeys.defaultEventSounds[eventId]!)); + } + break; + case StorageKeys.soundTypeCustom: + try { + await _audioPlayer.play(DeviceFileSource(value)); + } catch (e) { + Get.log('自定义音效播放失败,回退到默认: $e'); + await _audioPlayer.play(AssetSource(StorageKeys.defaultEventSounds[eventId]!)); + } + break; + case StorageKeys.soundTypeBuiltin: + default: + await _audioPlayer.play(AssetSource(value)); } - await _audioPlayer.play(AssetSource(assetPath)); } catch (e) { - // 使用 Get.log 替代 print Get.log('播放音频失败: $e'); } } diff --git a/lib/page/setting/controller.dart b/lib/page/setting/controller.dart index 36f5f69..ae781f3 100644 --- a/lib/page/setting/controller.dart +++ b/lib/page/setting/controller.dart @@ -4,6 +4,7 @@ import 'package:mmkv/mmkv.dart'; import 'package:time_machine/route/route_name.dart'; import '../../service/app_storage_service.dart'; +import '../../service/permission_service.dart'; import '../../database/backup_restore_db_service.dart'; import '../../config/storage_keys.dart'; import '../home/controller.dart'; @@ -263,6 +264,20 @@ class SettingController extends GetxController { /// 执行数据备份 Future performBackup() async { if (state.isBackupInProgress.value) return; + + // 申请存储权限 + final perm = Get.find(); + if (!await perm.requestStorage()) { + Get.snackbar( + '权限不足', + '备份需要存储权限, 请在「权限管理→存储权限」中授予后再试', + snackPosition: SnackPosition.TOP, + barBlur: 100, + duration: const Duration(seconds: 3), + ); + return; + } + BackupRestoreDBService backupRestoreDBService = Get.isRegistered() ? Get.find() : Get.put(BackupRestoreDBService()); @@ -307,6 +322,19 @@ class SettingController extends GetxController { Future performRestore() async { if (state.isRestoreInProgress.value) return; + // 申请存储权限 + final perm = Get.find(); + if (!await perm.requestStorage()) { + Get.snackbar( + '权限不足', + '恢复需要存储权限, 请在「权限管理→存储权限」中授予后再试', + snackPosition: SnackPosition.TOP, + barBlur: 100, + duration: const Duration(seconds: 3), + ); + return; + } + // 先显示确认对话框 final confirmed = await Get.dialog( AlertDialog( diff --git a/lib/page/setting/view.dart b/lib/page/setting/view.dart index f8a8c2f..381e57b 100644 --- a/lib/page/setting/view.dart +++ b/lib/page/setting/view.dart @@ -1,6 +1,7 @@ import 'package:flutter/material.dart'; import 'package:get/get.dart'; +import '../../route/route_name.dart'; import 'controller.dart'; import 'widgets/widgets.dart'; import 'widgets/theme_selector.dart'; @@ -157,6 +158,21 @@ class SettingPage extends StatelessWidget { const SizedBox(height: 24), + // 提示音设置入口(进入二级页面) + SettingSection( + title: '提示音', + children: [ + SettingTile( + title: '提示音设置', + subtitle: '为各计时事件单独选择提示音', + trailing: const Icon(Icons.chevron_right), + onTap: () => Get.toNamed(AppRoutes.SOUND_SETTINGS), + ), + ], + ), + + const SizedBox(height: 24), + // 显示设置组 SettingSection( title: '显示设置', @@ -189,6 +205,16 @@ class SettingPage extends StatelessWidget { const SizedBox(height: 24), + // 权限管理分组 + SettingSection( + title: '权限管理', + children: const [ + PermissionSettings(), + ], + ), + + const SizedBox(height: 24), + // 数据设置组 SettingSection( title: '数据设置', diff --git a/lib/page/setting/widgets/permission_settings.dart b/lib/page/setting/widgets/permission_settings.dart new file mode 100644 index 0000000..a48f06d --- /dev/null +++ b/lib/page/setting/widgets/permission_settings.dart @@ -0,0 +1,157 @@ +import 'package:flutter/material.dart'; +import 'package:get/get.dart'; +import 'package:permission_handler/permission_handler.dart'; + +import '../../../service/permission_service.dart'; +import 'setting_tile.dart'; +import 'setting_divider.dart'; + +/// 权限管理分组 +class PermissionSettings extends StatelessWidget { + const PermissionSettings({super.key}); + + @override + Widget build(BuildContext context) { + final perm = Get.find(); + + return Column( + children: [ + Obx(() => _PermissionRow( + title: '通知权限', + subtitle: '用于专注完成、休息开始等通知栏提醒', + status: perm.notificationStatus.value, + describe: perm.describeStatus(perm.notificationStatus.value), + onAction: () => _handleNotificationAction(perm), + )), + const SettingDivider(), + Obx(() => _PermissionRow( + title: '存储权限', + subtitle: '用于备份恢复数据到 Download 目录,以及读取自定义提示音', + status: perm.storageStatus.value, + describe: perm.describeStatus(perm.storageStatus.value), + onAction: () => _handleStorageAction(perm), + )), + const SettingDivider(), + Obx(() => _PermissionRow( + title: '电池优化白名单', + subtitle: '将本应用加入白名单, 确保后台计时不被系统终止. ' + '本应用后台仅运行计时器, 耗电极低', + status: perm.batteryStatus.value, + describe: perm.describeStatus(perm.batteryStatus.value), + onAction: () => _handleBatteryAction(perm), + )), + ], + ); + } + + Future _handleNotificationAction(PermissionService perm) async { + final s = perm.notificationStatus.value; + if (s.isPermanentlyDenied) { + _showOpenSettingsHint(); + await perm.openSettings(); + return; + } + await perm.requestNotification(); + } + + Future _handleStorageAction(PermissionService perm) async { + final s = perm.storageStatus.value; + if (s.isPermanentlyDenied) { + _showOpenSettingsHint(); + await perm.openSettings(); + return; + } + await perm.requestStorage(); + } + + Future _handleBatteryAction(PermissionService perm) async { + final s = perm.batteryStatus.value; + if (s.isPermanentlyDenied) { + _showOpenSettingsHint(); + await perm.openSettings(); + return; + } + await perm.requestBatteryWhitelist(); + } + + void _showOpenSettingsHint() { + Get.snackbar( + '需要在系统设置中手动开启', + '权限已被永久拒绝, 即将跳转到应用设置', + snackPosition: SnackPosition.TOP, + barBlur: 100, + duration: const Duration(seconds: 2), + ); + } +} + +class _PermissionRow extends StatelessWidget { + const _PermissionRow({ + required this.title, + required this.subtitle, + required this.status, + required this.describe, + required this.onAction, + }); + + final String title; + final String subtitle; + final PermissionStatus status; + final String describe; + final VoidCallback onAction; + + @override + Widget build(BuildContext context) { + final theme = Theme.of(context); + final granted = status.isGranted; + + return SettingTile( + title: title, + subtitle: subtitle, + trailing: granted + ? _StatusBadge(text: describe, color: Colors.green.shade600) + : ElevatedButton( + onPressed: onAction, + style: ElevatedButton.styleFrom( + backgroundColor: status.isPermanentlyDenied + ? theme.colorScheme.error + : null, + foregroundColor: status.isPermanentlyDenied + ? theme.colorScheme.onError + : null, + ), + child: Text(status.isPermanentlyDenied ? '去设置' : '去授权'), + ), + ); + } +} + +class _StatusBadge extends StatelessWidget { + const _StatusBadge({required this.text, required this.color}); + + final String text; + final Color color; + + @override + Widget build(BuildContext context) { + return Container( + padding: const EdgeInsets.symmetric(horizontal: 10, vertical: 4), + decoration: BoxDecoration( + color: color.withValues(alpha: 0.12), + borderRadius: BorderRadius.circular(12), + border: Border.all(color: color.withValues(alpha: 0.3)), + ), + child: Row( + mainAxisSize: MainAxisSize.min, + children: [ + Icon(Icons.check_circle, size: 14, color: color), + const SizedBox(width: 4), + Text( + text, + style: TextStyle(color: color, fontSize: 12, fontWeight: FontWeight.w600), + ), + ], + ), + ); + } +} diff --git a/lib/page/setting/widgets/pomodoro_settings.dart b/lib/page/setting/widgets/pomodoro_settings.dart index 8030191..bf87b5b 100644 --- a/lib/page/setting/widgets/pomodoro_settings.dart +++ b/lib/page/setting/widgets/pomodoro_settings.dart @@ -1,5 +1,4 @@ import 'package:flutter/material.dart'; -import 'package:get/get.dart'; import '../controller.dart'; import 'setting_tile.dart'; import 'time_input.dart'; diff --git a/lib/page/setting/widgets/setting_tile.dart b/lib/page/setting/widgets/setting_tile.dart index a2c3aba..2003392 100644 --- a/lib/page/setting/widgets/setting_tile.dart +++ b/lib/page/setting/widgets/setting_tile.dart @@ -7,18 +7,20 @@ class SettingTile extends StatelessWidget { required this.title, required this.subtitle, required this.trailing, + this.onTap, }); final String title; final String subtitle; final Widget trailing; + final VoidCallback? onTap; @override Widget build(BuildContext context) { final theme = Theme.of(context); final colorScheme = theme.colorScheme; - - return Padding( + + final content = Padding( padding: const EdgeInsets.symmetric(horizontal: 20, vertical: 16), child: Row( children: [ @@ -50,5 +52,11 @@ class SettingTile extends StatelessWidget { ], ), ); + + if (onTap == null) return content; + return InkWell( + onTap: onTap, + child: content, + ); } } diff --git a/lib/page/setting/widgets/widgets.dart b/lib/page/setting/widgets/widgets.dart index 6a4d4ec..497052b 100644 --- a/lib/page/setting/widgets/widgets.dart +++ b/lib/page/setting/widgets/widgets.dart @@ -10,3 +10,4 @@ export 'micro_break_settings.dart'; export 'developer_settings.dart'; export 'data_settings.dart'; export 'pomodoro_settings.dart'; +export 'permission_settings.dart'; diff --git a/lib/page/sound_settings/controller.dart b/lib/page/sound_settings/controller.dart new file mode 100644 index 0000000..4a11784 --- /dev/null +++ b/lib/page/sound_settings/controller.dart @@ -0,0 +1,249 @@ +import 'dart:async'; +import 'dart:io'; + +import 'package:audioplayers/audioplayers.dart'; +import 'package:file_picker/file_picker.dart'; +import 'package:get/get.dart'; +import 'package:mmkv/mmkv.dart'; +import 'package:path/path.dart' as p; + +import '../../config/storage_keys.dart'; +import '../../service/app_storage_service.dart'; +import '../../service/custom_sound_storage_service.dart'; +import '../../service/permission_service.dart'; +import '../../service/ringtone_picker_service.dart'; +import 'state.dart'; + +class SoundSettingsController extends GetxController { + final SoundSettingsState state = SoundSettingsState(); + final AudioPlayer _previewPlayer = AudioPlayer(); + late final MMKV _storage; + late final CustomSoundStorageService _customSoundStorage; + late final RingtonePickerService _ringtonePicker; + late final PermissionService _permissionService; + + StreamSubscription? _previewCompleteSub; + StreamSubscription? _systemCompleteSub; + + @override + void onInit() { + super.onInit(); + _storage = Get.find().mmkv; + _customSoundStorage = Get.find(); + _ringtonePicker = Get.find(); + _permissionService = Get.find(); + + // 内置 / 自定义试听播放完成 -> 复位按钮 + _previewCompleteSub = _previewPlayer.onPlayerComplete.listen((_) { + state.previewingTag.value = ''; + }); + + // 系统铃声试听播放完成 -> 复位按钮 + _systemCompleteSub = _ringtonePicker.onCompleted.listen((_) { + final tag = state.previewingTag.value; + if (tag.startsWith('system:')) { + state.previewingTag.value = ''; + } + }); + + _loadAll(); + } + + @override + void onClose() { + _previewCompleteSub?.cancel(); + _systemCompleteSub?.cancel(); + _previewPlayer.dispose(); + _ringtonePicker.stopSystemRingtone(); + super.onClose(); + } + + void _loadAll() { + for (final eventId in StorageKeys.soundEventIds) { + state.configs[eventId] = _readEvent(eventId); + } + } + + SoundEventConfig _readEvent(String eventId) { + final type = _storage.decodeString(StorageKeys.soundTypeKey(eventId)) ?? + StorageKeys.soundTypeBuiltin; + final value = _storage.decodeString(StorageKeys.soundValueKey(eventId)) ?? + StorageKeys.defaultEventSounds[eventId]!; + // storedName: system 类型存铃声标题(uri 非文件路径无法取名); + // custom 类型存用户选择文件的原始文件名(磁盘上文件按 eventId 命名)。 + final storedName = + _storage.decodeString(StorageKeys.soundDisplayNameKey(eventId)); + return SoundEventConfig( + type: type, + value: value, + displayName: _resolveDisplayName(type, value, storedName), + ); + } + + String _resolveDisplayName(String type, String value, String? storedName) { + switch (type) { + case StorageKeys.soundTypeBuiltin: + return StorageKeys.builtinSounds[value] ?? p.basename(value); + case StorageKeys.soundTypeCustom: + if (storedName != null && storedName.isNotEmpty) return storedName; + return p.basename(value); + case StorageKeys.soundTypeSystem: + if (storedName != null && storedName.isNotEmpty) return storedName; + return '系统铃声'; + default: + return '默认'; + } + } + + /// 选择内置 + Future selectBuiltin(String eventId, String assetPath) async { + await stopAllPreview(); + _storage.encodeString(StorageKeys.soundTypeKey(eventId), StorageKeys.soundTypeBuiltin); + _storage.encodeString(StorageKeys.soundValueKey(eventId), assetPath); + _storage.removeValue(StorageKeys.soundDisplayNameKey(eventId)); + state.configs[eventId] = _readEvent(eventId); + state.configs.refresh(); + } + + /// 选择系统铃声 + Future selectSystem(String eventId) async { + await stopAllPreview(); + final current = _storage.decodeString(StorageKeys.soundValueKey(eventId)); + final picked = await _ringtonePicker.pickSystemRingtone(currentUri: current); + if (picked == null) return; + _storage.encodeString(StorageKeys.soundTypeKey(eventId), StorageKeys.soundTypeSystem); + _storage.encodeString(StorageKeys.soundValueKey(eventId), picked.uri); + Get.log(picked.uri); + _storage.encodeString(StorageKeys.soundDisplayNameKey(eventId), picked.title); + state.configs[eventId] = SoundEventConfig( + type: StorageKeys.soundTypeSystem, + value: picked.uri, + displayName: picked.title, + ); + state.configs.refresh(); + } + + /// 选择文件管理器自定义 + Future selectCustom(String eventId) async { + await stopAllPreview(); + + // Android 13+ 需要 READ_MEDIA_AUDIO + final granted = await _permissionService.requestAudioRead(); + if (!granted) { + Get.snackbar( + '权限不足', + '请授予音频读取权限后重试', + snackPosition: SnackPosition.TOP, + barBlur: 100, + duration: const Duration(seconds: 2), + ); + return; + } + + final result = await FilePicker.platform.pickFiles( + type: FileType.audio, + dialogTitle: '选择音频文件', + ); + if (result == null || result.files.isEmpty) return; + final src = result.files.first.path; + if (src == null) return; + // 文件管理器选中文件的原始名(含扩展名),仅用于展示 + final originalName = result.files.first.name; + + final dest = await _customSoundStorage.importCustomSound(eventId, src); + if (dest == null) { + Get.snackbar( + '导入失败', + '无法保存自定义音效', + snackPosition: SnackPosition.TOP, + barBlur: 100, + duration: const Duration(seconds: 2), + ); + return; + } + _storage.encodeString(StorageKeys.soundTypeKey(eventId), StorageKeys.soundTypeCustom); + _storage.encodeString(StorageKeys.soundValueKey(eventId), dest); + _storage.encodeString(StorageKeys.soundDisplayNameKey(eventId), originalName); + state.configs[eventId] = SoundEventConfig( + type: StorageKeys.soundTypeCustom, + value: dest, + displayName: originalName, + ); + state.configs.refresh(); + } + + /// 重置为默认 + Future resetToDefault(String eventId) async { + await stopAllPreview(); + final defaultPath = StorageKeys.defaultEventSounds[eventId]!; + _storage.encodeString(StorageKeys.soundTypeKey(eventId), StorageKeys.soundTypeBuiltin); + _storage.encodeString(StorageKeys.soundValueKey(eventId), defaultPath); + _storage.removeValue(StorageKeys.soundDisplayNameKey(eventId)); + state.configs[eventId] = _readEvent(eventId); + state.configs.refresh(); + } + + /// 试听 + Future previewBuiltin(String assetPath) async { + final tag = 'builtin:$assetPath'; + // 播放状态再点击为停止 + if (state.previewingTag.value == tag) { + await stopAllPreview(); + return; + } + await stopAllPreview(); + state.previewingTag.value = tag; + try { + await _previewPlayer.play(AssetSource(assetPath)); + } catch (e) { + Get.log('试听失败: $e'); + state.previewingTag.value = ''; + } + } + + Future previewCustom(String filePath) async { + final tag = 'custom:$filePath'; + if (state.previewingTag.value == tag) { + await stopAllPreview(); + return; + } + await stopAllPreview(); + if (!await File(filePath).exists()) { + Get.snackbar( + '试听失败', + '文件不存在', + snackPosition: SnackPosition.TOP, + barBlur: 100, + duration: const Duration(seconds: 2), + ); + return; + } + state.previewingTag.value = tag; + try { + await _previewPlayer.play(DeviceFileSource(filePath)); + } catch (e) { + Get.log('试听自定义失败: $e'); + state.previewingTag.value = ''; + } + } + + Future previewSystem(String uri) async { + final tag = 'system:$uri'; + if (state.previewingTag.value == tag) { + await stopAllPreview(); + return; + } + await stopAllPreview(); + state.previewingTag.value = tag; + final ok = await _ringtonePicker.playSystemRingtone(uri); + if (!ok) state.previewingTag.value = ''; + } + + Future stopAllPreview() async { + if (_previewPlayer.state == PlayerState.playing) { + await _previewPlayer.stop(); + } + await _ringtonePicker.stopSystemRingtone(); + state.previewingTag.value = ''; + } +} diff --git a/lib/page/sound_settings/state.dart b/lib/page/sound_settings/state.dart new file mode 100644 index 0000000..8283db8 --- /dev/null +++ b/lib/page/sound_settings/state.dart @@ -0,0 +1,29 @@ +import 'package:get/get.dart'; + +class SoundEventConfig { + final String type; + final String value; + final String displayName; + + const SoundEventConfig({ + required this.type, + required this.value, + required this.displayName, + }); + + SoundEventConfig copyWith({String? type, String? value, String? displayName}) { + return SoundEventConfig( + type: type ?? this.type, + value: value ?? this.value, + displayName: displayName ?? this.displayName, + ); + } +} + +class SoundSettingsState { + /// eventId -> 当前选择 + final RxMap configs = {}.obs; + + /// 当前正在试听的标识(eventId 或 builtin 资源路径) + final RxString previewingTag = ''.obs; +} diff --git a/lib/page/sound_settings/view.dart b/lib/page/sound_settings/view.dart new file mode 100644 index 0000000..11f531c --- /dev/null +++ b/lib/page/sound_settings/view.dart @@ -0,0 +1,88 @@ +import 'package:flutter/material.dart'; +import 'package:get/get.dart'; + +import '../../config/storage_keys.dart'; +import '../setting/widgets/setting_section.dart'; +import '../setting/widgets/setting_tile.dart'; +import '../setting/widgets/setting_divider.dart'; +import 'controller.dart'; +import 'widgets/sound_picker_dialog.dart'; + +class SoundSettingsPage extends StatelessWidget { + const SoundSettingsPage({super.key}); + + @override + Widget build(BuildContext context) { + final controller = Get.isRegistered() + ? Get.find() + : Get.put(SoundSettingsController()); + final theme = Theme.of(context); + + return Scaffold( + appBar: AppBar( + title: Text( + '提示音设置', + style: theme.textTheme.titleLarge?.copyWith(fontWeight: FontWeight.w600), + ), + centerTitle: true, + ), + body: SafeArea( + child: ListView( + padding: const EdgeInsets.symmetric(horizontal: 16.0, vertical: 16.0), + children: [ + SettingSection( + title: '事件提示音', + children: [ + for (int i = 0; i < StorageKeys.soundEventIds.length; i++) ...[ + _buildEventTile(controller, StorageKeys.soundEventIds[i]), + if (i != StorageKeys.soundEventIds.length - 1) const SettingDivider(), + ], + ], + ), + const SizedBox(height: 24), + SettingSection( + title: '说明', + children: [ + Padding( + padding: const EdgeInsets.all(20), + child: Text( + '• 内置音效: 应用自带的几个提示音\n' + '• 系统铃声: 从系统铃声/通知音中选择\n' + '• 自定义: 通过文件管理器选择本机音频文件', + style: theme.textTheme.bodySmall?.copyWith( + color: theme.colorScheme.onSurfaceVariant, + height: 1.6, + ), + ), + ), + ], + ), + const SizedBox(height: 24), + ], + ), + ), + ); + } + + Widget _buildEventTile(SoundSettingsController controller, String eventId) { + return Obx(() { + final config = controller.state.configs[eventId]; + final displayName = config?.displayName ?? '默认'; + return SettingTile( + title: StorageKeys.eventDisplayNames[eventId] ?? eventId, + subtitle: '当前: $displayName', + trailing: const Icon(Icons.chevron_right), + onTap: () => _openPicker(controller, eventId), + ); + }); + } + + Future _openPicker(SoundSettingsController controller, String eventId) async { + await Get.dialog( + SoundPickerDialog(controller: controller, eventId: eventId), + barrierDismissible: true, + ); + // dialog 以任意方式关闭(按钮/遮罩/返回手势)后停止所有试听 + await controller.stopAllPreview(); + } +} diff --git a/lib/page/sound_settings/widgets/sound_picker_dialog.dart b/lib/page/sound_settings/widgets/sound_picker_dialog.dart new file mode 100644 index 0000000..674285a --- /dev/null +++ b/lib/page/sound_settings/widgets/sound_picker_dialog.dart @@ -0,0 +1,217 @@ +import 'package:flutter/material.dart'; +import 'package:get/get.dart'; + +import '../../../config/storage_keys.dart'; +import '../controller.dart'; + +class SoundPickerDialog extends StatelessWidget { + const SoundPickerDialog({ + super.key, + required this.controller, + required this.eventId, + }); + + final SoundSettingsController controller; + final String eventId; + + @override + Widget build(BuildContext context) { + final theme = Theme.of(context); + final eventName = StorageKeys.eventDisplayNames[eventId] ?? eventId; + + return Dialog( + shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(16)), + child: ConstrainedBox( + constraints: BoxConstraints( + maxHeight: MediaQuery.of(context).size.height * 0.75, + maxWidth: 480, + ), + child: Column( + mainAxisSize: MainAxisSize.min, + children: [ + Padding( + padding: const EdgeInsets.fromLTRB(20, 20, 20, 12), + child: Row( + children: [ + Expanded( + child: Text( + '为「$eventName」选择提示音', + style: theme.textTheme.titleMedium?.copyWith(fontWeight: FontWeight.w600), + ), + ), + IconButton( + onPressed: () => _confirmReset(context, eventName), + tooltip: '恢复默认', + icon: const Icon(Icons.restart_alt), + ), + ], + ), + ), + // const Divider(height: 1), + Expanded( + child: SingleChildScrollView( + padding: const EdgeInsets.symmetric(vertical: 8), + child: Column( + children: [ + _buildBuiltinGroup(theme), + _buildSystemGroup(theme), + _buildCustomGroup(theme), + ], + ), + ), + ), + const Divider(height: 1), + Padding( + padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 8), + child: Row( + mainAxisAlignment: MainAxisAlignment.end, + children: [ + TextButton( + onPressed: () => Get.back(), + child: const Text('关闭'), + ), + ], + ), + ), + ], + ), + ), + ); + } + + Future _confirmReset(BuildContext context, String eventName) async { + final confirmed = await showDialog( + context: context, + builder: (ctx) => AlertDialog( + title: const Text('恢复默认'), + content: Text('确定将「$eventName」恢复为默认提示音?'), + actions: [ + TextButton( + onPressed: () => Navigator.of(ctx).pop(false), + child: const Text('取消'), + ), + TextButton( + onPressed: () => Navigator.of(ctx).pop(true), + child: const Text('确定'), + ), + ], + ), + ); + if (confirmed == true) { + controller.resetToDefault(eventId); + Get.back(); + } + } + + Widget _buildBuiltinGroup(ThemeData theme) { + return ExpansionTile( + // initiallyExpanded: true, + title: const Text('内置音效'), + childrenPadding: const EdgeInsets.symmetric(horizontal: 8), + children: StorageKeys.builtinSounds.entries.map((e) { + final assetPath = e.key; + final name = e.value; + return Obx(() { + final config = controller.state.configs[eventId]; + final isSelected = config?.type == StorageKeys.soundTypeBuiltin && config?.value == assetPath; + final isPreviewing = controller.state.previewingTag.value == 'builtin:$assetPath'; + return ListTile( + dense: true, + leading: Icon( + isSelected ? Icons.radio_button_checked : Icons.radio_button_unchecked, + color: isSelected ? theme.colorScheme.primary : theme.colorScheme.onSurfaceVariant, + ), + title: Text(name), + subtitle: Text( + assetPath, + style: theme.textTheme.bodySmall?.copyWith(color: theme.colorScheme.onSurfaceVariant), + ), + trailing: IconButton( + onPressed: () => controller.previewBuiltin(assetPath), + icon: Icon(isPreviewing ? Icons.stop : Icons.play_arrow), + tooltip: isPreviewing ? '停止' : '试听', + ), + onTap: () => controller.selectBuiltin(eventId, assetPath), + ); + }); + }).toList(), + ); + } + + Widget _buildSystemGroup(ThemeData theme) { + return ExpansionTile( + title: const Text('系统铃声'), + childrenPadding: const EdgeInsets.symmetric(horizontal: 8), + children: [ + Obx(() { + final config = controller.state.configs[eventId]; + final isSelected = config?.type == StorageKeys.soundTypeSystem; + final isPreviewing = isSelected && + config != null && + controller.state.previewingTag.value == 'system:${config.value}'; + return ListTile( + dense: true, + leading: Icon( + isSelected ? Icons.radio_button_checked : Icons.radio_button_unchecked, + color: isSelected ? theme.colorScheme.primary : theme.colorScheme.onSurfaceVariant, + ), + title: Text(isSelected ? (config?.displayName ?? '系统铃声') : '点击选择系统铃声'), + subtitle: isSelected + ? Text('已选: ${config?.displayName ?? '未知铃声'}', + style: theme.textTheme.bodySmall + ?.copyWith(color: theme.colorScheme.onSurfaceVariant)) + : null, + trailing: isSelected && config != null + ? IconButton( + onPressed: () => controller.previewSystem(config.value), + icon: Icon(isPreviewing ? Icons.stop : Icons.play_arrow), + tooltip: isPreviewing ? '停止' : '试听', + ) + : const Icon(Icons.chevron_right), + onTap: () => controller.selectSystem(eventId), + ); + }), + ], + ); + } + + Widget _buildCustomGroup(ThemeData theme) { + return ExpansionTile( + title: const Text('自定义(从文件选择)'), + childrenPadding: const EdgeInsets.symmetric(horizontal: 8), + children: [ + Obx(() { + final config = controller.state.configs[eventId]; + final isSelected = config?.type == StorageKeys.soundTypeCustom; + final isPreviewing = isSelected && + config != null && + controller.state.previewingTag.value == 'custom:${config.value}'; + return ListTile( + dense: true, + leading: Icon( + isSelected ? Icons.radio_button_checked : Icons.radio_button_unchecked, + color: isSelected ? theme.colorScheme.primary : theme.colorScheme.onSurfaceVariant, + ), + title: Text(isSelected ? (config?.displayName ?? '自定义') : '点击选择本地音频'), + subtitle: isSelected + ? Text( + config?.value ?? '', + style: theme.textTheme.bodySmall + ?.copyWith(color: theme.colorScheme.onSurfaceVariant), + overflow: TextOverflow.ellipsis, + ) + : null, + trailing: isSelected && config != null + ? IconButton( + onPressed: () => controller.previewCustom(config.value), + icon: Icon(isPreviewing ? Icons.stop : Icons.play_arrow), + tooltip: isPreviewing ? '停止' : '试听', + ) + : const Icon(Icons.chevron_right), + onTap: () => controller.selectCustom(eventId), + ); + }), + ], + ); + } +} diff --git a/lib/route/route_name.dart b/lib/route/route_name.dart index 45044b0..18ceddc 100644 --- a/lib/route/route_name.dart +++ b/lib/route/route_name.dart @@ -9,6 +9,7 @@ abstract class AppRoutes { static const String MAIN = '/main'; static const String HOME = '/home'; static const String SETTING = '/setting'; + static const String SOUND_SETTINGS = '/sound_settings'; static const String OTHER = "/other"; static const String ABOUT = '/about'; static const String DONATE = '/donate'; diff --git a/lib/route/route_page.dart b/lib/route/route_page.dart index a8f0d01..a1a71e9 100644 --- a/lib/route/route_page.dart +++ b/lib/route/route_page.dart @@ -5,6 +5,7 @@ import '../page/test/view.dart'; import '../page/main/view.dart'; import '../page/home/view.dart'; import '../page/setting/view.dart'; +import '../page/sound_settings/view.dart'; import '../page/about/view.dart'; import '../page/donate/view.dart'; @@ -17,6 +18,7 @@ class AppPages { GetPage(name: AppRoutes.TEST, page: () => TestPage()), GetPage(name: AppRoutes.HOME, page: () => HomePage()), GetPage(name: AppRoutes.SETTING, page: () => SettingPage()), + GetPage(name: AppRoutes.SOUND_SETTINGS, page: () => const SoundSettingsPage()), GetPage(name: AppRoutes.OTHER, page: () => Other()), GetPage(name: AppRoutes.ABOUT, page: () => const AboutPage()), GetPage(name: AppRoutes.DONATE, page: () => const DonatePage()), diff --git a/lib/service/custom_sound_storage_service.dart b/lib/service/custom_sound_storage_service.dart new file mode 100644 index 0000000..f84784a --- /dev/null +++ b/lib/service/custom_sound_storage_service.dart @@ -0,0 +1,140 @@ +import 'dart:io'; + +import 'package:get/get.dart'; +import 'package:mmkv/mmkv.dart'; +import 'package:path/path.dart' as p; +import 'package:path_provider/path_provider.dart'; + +import '../config/storage_keys.dart'; +import 'app_storage_service.dart'; + +/// 自定义提示音文件管理 +/// +/// 把用户通过文件管理器选中的音频复制到应用私有目录, +/// 避免源文件被删除/移动/无权访问导致播放失败。 +/// +/// 目录: `getApplicationDocumentsDirectory()/sounds/.` +class CustomSoundStorageService extends GetxService { + late final MMKV _storage; + Directory? _soundsDir; + + Future init() async { + _storage = Get.find().mmkv; + _soundsDir = await _ensureSoundsDir(); + await cleanupOrphans(); + return this; + } + + Future _ensureSoundsDir() async { + final docDir = await getApplicationDocumentsDirectory(); + final dir = Directory(p.join(docDir.path, 'sounds')); + if (!await dir.exists()) { + await dir.create(recursive: true); + } + return dir; + } + + Future get soundsDir async { + return _soundsDir ??= await _ensureSoundsDir(); + } + + /// 把外部音频文件复制到私有目录 + /// 返回复制后的绝对路径,失败返回 null + Future importCustomSound(String eventId, String sourcePath) async { + try { + final src = File(sourcePath); + if (!await src.exists()) { + Get.log('源文件不存在: $sourcePath'); + return null; + } + + // 删掉该 eventId 的旧自定义音(如果有) + await _deleteExistingForEvent(eventId); + + final ext = p.extension(sourcePath); // 含点符号 + final dir = await soundsDir; + final dest = File(p.join(dir.path, '$eventId$ext')); + await src.copy(dest.path); + + Get.log('自定义音效已保存: ${dest.path}'); + return dest.path; + } catch (e) { + Get.log('保存自定义音效失败: $e'); + return null; + } + } + + /// 清除指定事件的自定义音文件(不动 MMKV 配置) + Future _deleteExistingForEvent(String eventId) async { + final dir = await soundsDir; + if (!await dir.exists()) return; + await for (final entity in dir.list()) { + if (entity is File) { + final name = p.basenameWithoutExtension(entity.path); + if (name == eventId) { + try { + await entity.delete(); + } catch (e) { + Get.log('删除旧自定义音失败: $e'); + } + } + } + } + } + + /// 启动时清理 MMKV 没在引用的孤儿文件 + Future cleanupOrphans() async { + try { + final dir = await soundsDir; + if (!await dir.exists()) return; + + // 收集所有事件当前引用的 custom 路径 + final referenced = {}; + for (final eventId in StorageKeys.soundEventIds) { + final type = _storage.decodeString(StorageKeys.soundTypeKey(eventId)); + if (type == StorageKeys.soundTypeCustom) { + final path = _storage.decodeString(StorageKeys.soundValueKey(eventId)); + if (path != null && path.isNotEmpty) { + referenced.add(path); + } + } + } + + await for (final entity in dir.list()) { + if (entity is File && !referenced.contains(entity.path)) { + try { + await entity.delete(); + Get.log('清理孤儿音效: ${entity.path}'); + } catch (e) { + Get.log('清理孤儿音效失败: $e'); + } + } + } + } catch (e) { + Get.log('cleanupOrphans 异常: $e'); + } + } + + /// 重置数据库时清空所有自定义音 + Future clearAllCustomSounds() async { + try { + final dir = await soundsDir; + if (!await dir.exists()) return; + await for (final entity in dir.list()) { + if (entity is File) { + try { + await entity.delete(); + } catch (_) {} + } + } + } catch (e) { + Get.log('clearAllCustomSounds 异常: $e'); + } + } + + /// 检查文件是否还存在 + Future fileExists(String path) async { + if (path.isEmpty) return false; + return File(path).exists(); + } +} diff --git a/lib/service/permission_service.dart b/lib/service/permission_service.dart new file mode 100644 index 0000000..703dacd --- /dev/null +++ b/lib/service/permission_service.dart @@ -0,0 +1,102 @@ +import 'dart:io'; + +import 'package:device_info_plus/device_info_plus.dart'; +import 'package:get/get.dart'; +import 'package:permission_handler/permission_handler.dart'; + +/// 应用权限统一管理服务 +/// +/// 三类权限: +/// - 通知 (Permission.notification) +/// - 存储 (Android 13+ 走 manageExternalStorage,12 及以下走 storage) +/// - 电池优化白名单 (Permission.ignoreBatteryOptimizations) +class PermissionService extends GetxService { + // 各权限当前状态(响应式) + final Rx notificationStatus = PermissionStatus.denied.obs; + final Rx storageStatus = PermissionStatus.denied.obs; + final Rx batteryStatus = PermissionStatus.denied.obs; + + int _androidSdkInt = 0; + + Future init() async { + if (Platform.isAndroid) { + try { + final info = await DeviceInfoPlugin().androidInfo; + _androidSdkInt = info.version.sdkInt; + } catch (e) { + Get.log('读取 Android SDK 版本失败: $e'); + } + } + await refreshAll(); + return this; + } + + /// 应用回前台时主动调用,刷新各权限状态 + Future refreshAll() async { + notificationStatus.value = await _resolveNotificationStatus(); + storageStatus.value = await _resolveStorageStatus(); + batteryStatus.value = await Permission.ignoreBatteryOptimizations.status; + } + + Future _resolveNotificationStatus() async { + return Permission.notification.status; + } + + Future _resolveStorageStatus() async { + if (Platform.isAndroid && _androidSdkInt >= 30) { + // Android 11+ 用 MANAGE_EXTERNAL_STORAGE 才能写 Download 目录 + return Permission.manageExternalStorage.status; + } + return Permission.storage.status; + } + + /// 请求通知权限 + Future requestNotification() async { + final status = await Permission.notification.request(); + notificationStatus.value = status; + return status.isGranted; + } + + /// 请求存储权限(根据系统版本走不同分支) + Future requestStorage() async { + PermissionStatus status; + if (Platform.isAndroid && _androidSdkInt >= 30) { + status = await Permission.manageExternalStorage.request(); + } else { + status = await Permission.storage.request(); + } + storageStatus.value = status; + return status.isGranted; + } + + /// 请求电池优化白名单(实际是引导用户跳到系统对话框) + Future requestBatteryWhitelist() async { + final status = await Permission.ignoreBatteryOptimizations.request(); + batteryStatus.value = status; + return status.isGranted; + } + + /// 读取音频文件需要的权限(Android 13+ READ_MEDIA_AUDIO) + Future requestAudioRead() async { + if (!Platform.isAndroid) return true; + if (_androidSdkInt >= 33) { + final status = await Permission.audio.request(); + return status.isGranted; + } + final status = await Permission.storage.request(); + return status.isGranted; + } + + /// 状态文案 + String describeStatus(PermissionStatus status) { + if (status.isGranted) return '已开启'; + if (status.isPermanentlyDenied) return '已拒绝, 请去系统设置'; + if (status.isRestricted) return '系统限制'; + return '未授权'; + } + + /// 跳转到应用设置页 + Future openSettings() async { + await openAppSettings(); + } +} diff --git a/lib/service/ringtone_picker_service.dart b/lib/service/ringtone_picker_service.dart new file mode 100644 index 0000000..b0c4962 --- /dev/null +++ b/lib/service/ringtone_picker_service.dart @@ -0,0 +1,93 @@ +import 'dart:async'; + +import 'package:flutter/services.dart'; +import 'package:get/get.dart'; + +/// 系统铃声选择/播放(走 MethodChannel,原生 RingtoneManager / MediaPlayer 实现) +class RingtonePickerService extends GetxService { + static const MethodChannel _channel = + MethodChannel('top.merack.time_machine/ringtone'); + + final StreamController _completionController = + StreamController.broadcast(); + + /// 系统铃声"自然播放完成"事件流(stopRingtone 主动停止不会触发) + Stream get onCompleted => _completionController.stream; + + @override + void onInit() { + super.onInit(); + _channel.setMethodCallHandler(_onNativeCall); + } + + @override + void onClose() { + _channel.setMethodCallHandler(null); + _completionController.close(); + super.onClose(); + } + + Future _onNativeCall(MethodCall call) async { + if (call.method == 'onRingtoneCompleted') { + if (!_completionController.isClosed) { + // 往stream里加入信号 + _completionController.add(null); + } + } + return null; + } + + /// 弹出系统铃声选择器,返回 {uri, title} 或 null + Future pickSystemRingtone({String? currentUri}) async { + try { + final result = await _channel.invokeMethod>( + 'pickRingtone', + {'currentUri': currentUri}, + ); + if (result == null) return null; + final uri = result['uri'] as String?; + final title = (result['title'] as String?) ?? '系统铃声'; + if (uri == null || uri.isEmpty) return null; + return RingtoneSelection(uri: uri, title: title); + } on PlatformException catch (e) { + Get.log('pickSystemRingtone 失败: $e'); + return null; + } + } + + /// 播放系统铃声(用于试听 / 计时事件触发) + Future playSystemRingtone(String uri) async { + try { + final ok = await _channel.invokeMethod('playRingtone', {'uri': uri}); + return ok ?? false; + } on PlatformException catch (e) { + Get.log('playSystemRingtone 失败: $e'); + return false; + } + } + + /// 停止当前系统铃声播放 + Future stopSystemRingtone() async { + try { + await _channel.invokeMethod('stopRingtone'); + } on PlatformException catch (e) { + Get.log('stopSystemRingtone 失败: $e'); + } + } + + /// 根据 URI 取标题(用于显示当前选中) + Future getRingtoneTitle(String uri) async { + try { + return await _channel.invokeMethod('getRingtoneTitle', {'uri': uri}); + } on PlatformException catch (e) { + Get.log('getRingtoneTitle 失败: $e'); + return null; + } + } +} + +class RingtoneSelection { + final String uri; + final String title; + const RingtoneSelection({required this.uri, required this.title}); +} diff --git a/pubspec.lock b/pubspec.lock index 16d7280..9367b85 100644 --- a/pubspec.lock +++ b/pubspec.lock @@ -428,10 +428,10 @@ packages: dependency: transitive description: name: matcher - sha256: "12956d0ad8390bbcc63ca2e1469c0619946ccb52809807067a7020d57e647aa6" + sha256: dc0b7dc7651697ea4ff3e69ef44b0407ea32c487a39fff6a4004fa585e901861 url: "https://pub.flutter-io.cn" source: hosted - version: "0.12.18" + version: "0.12.19" material_color_utilities: dependency: transitive description: @@ -444,10 +444,10 @@ packages: dependency: transitive description: name: meta - sha256: "23f08335362185a5ea2ad3a4e597f1375e78bce8a040df5c600c8d3552ef2394" + sha256: "1741988757a65eb6b36abe716829688cf01910bbf91c34354ff7ec1c3de2b349" url: "https://pub.flutter-io.cn" source: hosted - version: "1.17.0" + version: "1.18.0" mmkv: dependency: "direct main" description: @@ -592,6 +592,54 @@ packages: url: "https://pub.flutter-io.cn" source: hosted version: "2.3.0" + permission_handler: + dependency: "direct main" + description: + name: permission_handler + sha256: bc917da36261b00137bbc8896bf1482169cd76f866282368948f032c8c1caae1 + url: "https://pub.flutter-io.cn" + source: hosted + version: "12.0.1" + permission_handler_android: + dependency: transitive + description: + name: permission_handler_android + sha256: "1e3bc410ca1bf84662104b100eb126e066cb55791b7451307f9708d4007350e6" + url: "https://pub.flutter-io.cn" + source: hosted + version: "13.0.1" + permission_handler_apple: + dependency: transitive + description: + name: permission_handler_apple + sha256: f000131e755c54cf4d84a5d8bd6e4149e262cc31c5a8b1d698de1ac85fa41023 + url: "https://pub.flutter-io.cn" + source: hosted + version: "9.4.7" + permission_handler_html: + dependency: transitive + description: + name: permission_handler_html + sha256: "38f000e83355abb3392140f6bc3030660cfaef189e1f87824facb76300b4ff24" + url: "https://pub.flutter-io.cn" + source: hosted + version: "0.1.3+5" + permission_handler_platform_interface: + dependency: transitive + description: + name: permission_handler_platform_interface + sha256: eb99b295153abce5d683cac8c02e22faab63e50679b937fa1bf67d58bb282878 + url: "https://pub.flutter-io.cn" + source: hosted + version: "4.3.0" + permission_handler_windows: + dependency: transitive + description: + name: permission_handler_windows + sha256: "1a790728016f79a41216d88672dbc5df30e686e811ad4e698bfc51f76ad91f1e" + url: "https://pub.flutter-io.cn" + source: hosted + version: "0.2.1" petitparser: dependency: transitive description: @@ -729,10 +777,10 @@ packages: dependency: transitive description: name: test_api - sha256: "93167629bfc610f71560ab9312acdda4959de4df6fac7492c89ff0d3886f6636" + sha256: "949a932224383300f01be9221c39180316445ecb8e7547f70a41a35bf421fb9e" url: "https://pub.flutter-io.cn" source: hosted - version: "0.7.9" + version: "0.7.11" timezone: dependency: transitive description: diff --git a/pubspec.yaml b/pubspec.yaml index d9d7f76..56a6532 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -42,6 +42,7 @@ dependencies: package_info_plus: ^9.0.0 file_picker: ^10.2.0 path_provider: ^2.1.5 + permission_handler: ^12.0.0+1 # The following adds the Cupertino Icons font to your application. # Use with the CupertinoIcons class for iOS style icons. diff --git a/skills-lock.json b/skills-lock.json new file mode 100644 index 0000000..cec2f2c --- /dev/null +++ b/skills-lock.json @@ -0,0 +1,119 @@ +{ + "version": 1, + "skills": { + "dart-add-unit-test": { + "source": "dart-lang/skills", + "sourceType": "github", + "skillPath": "skills/dart-add-unit-test/SKILL.md", + "computedHash": "b4d913eb86f9a8539b5d07d453ce213c3b1557b028569eb980e1ae6707165da6" + }, + "dart-build-cli-app": { + "source": "dart-lang/skills", + "sourceType": "github", + "skillPath": "skills/dart-build-cli-app/SKILL.md", + "computedHash": "c8cd77f77250ad0783152e180de4fbec149c76e6b2c51c3f0d265a64c7466f0a" + }, + "dart-collect-coverage": { + "source": "dart-lang/skills", + "sourceType": "github", + "skillPath": "skills/dart-collect-coverage/SKILL.md", + "computedHash": "abaf27c3fe7370e4daaea2c48f6efd8cc418042e2844649a9c2979bbfde8b7b1" + }, + "dart-fix-runtime-errors": { + "source": "dart-lang/skills", + "sourceType": "github", + "skillPath": "skills/dart-fix-runtime-errors/SKILL.md", + "computedHash": "5d297ccaf9a34c5939c80600ff8398437c0c6bd5d343093852b65559689fae1d" + }, + "dart-generate-test-mocks": { + "source": "dart-lang/skills", + "sourceType": "github", + "skillPath": "skills/dart-generate-test-mocks/SKILL.md", + "computedHash": "c5132b41dd1d00949d035f6d49fcaee79e95d056eb9652d465e7349f539d16a2" + }, + "dart-migrate-to-checks-package": { + "source": "dart-lang/skills", + "sourceType": "github", + "skillPath": "skills/dart-migrate-to-checks-package/SKILL.md", + "computedHash": "c9e99ca93c56a78000d1afd1bbe9abdd263d0568ec3993b4034365dd663e0838" + }, + "dart-resolve-package-conflicts": { + "source": "dart-lang/skills", + "sourceType": "github", + "skillPath": "skills/dart-resolve-package-conflicts/SKILL.md", + "computedHash": "4f8029de67b9b2da43eea381c6a320a0da8844d927781effcce6e07ac736dffd" + }, + "dart-run-static-analysis": { + "source": "dart-lang/skills", + "sourceType": "github", + "skillPath": "skills/dart-run-static-analysis/SKILL.md", + "computedHash": "7b143ff93bfb118ce9d72fca56cef4b38d75bfe9044367101db09cf32e6815ad" + }, + "dart-use-pattern-matching": { + "source": "dart-lang/skills", + "sourceType": "github", + "skillPath": "skills/dart-use-pattern-matching/SKILL.md", + "computedHash": "4900ea465cfec31cd83d8786491609dc94e338ec8c424a1530773b2aaa0832ff" + }, + "flutter-add-integration-test": { + "source": "flutter/skills", + "sourceType": "github", + "skillPath": "skills/flutter-add-integration-test/SKILL.md", + "computedHash": "4246d3ef5f21bdb7945899056b99cf3863e2bff645a132b41634caaded68da6d" + }, + "flutter-add-widget-preview": { + "source": "flutter/skills", + "sourceType": "github", + "skillPath": "skills/flutter-add-widget-preview/SKILL.md", + "computedHash": "369ed3ebdc1f81ee337551ad1d1dd9ec6e768ed2bdf65d32ad442117a6ba79b6" + }, + "flutter-add-widget-test": { + "source": "flutter/skills", + "sourceType": "github", + "skillPath": "skills/flutter-add-widget-test/SKILL.md", + "computedHash": "f4ea905ae155d1bca76f5431bf6ed31f31e3d40146493e7ae4285eac39ba4ffd" + }, + "flutter-apply-architecture-best-practices": { + "source": "flutter/skills", + "sourceType": "github", + "skillPath": "skills/flutter-apply-architecture-best-practices/SKILL.md", + "computedHash": "baeb208b1cab90c559677626dbd101b96ba93f803cbed85122abdadeb3283a8b" + }, + "flutter-build-responsive-layout": { + "source": "flutter/skills", + "sourceType": "github", + "skillPath": "skills/flutter-build-responsive-layout/SKILL.md", + "computedHash": "6d74a9504c4e355c4c62f6fcb6c6dc0df67b56dd6616bea199e4e58f75b7729b" + }, + "flutter-fix-layout-issues": { + "source": "flutter/skills", + "sourceType": "github", + "skillPath": "skills/flutter-fix-layout-issues/SKILL.md", + "computedHash": "b2f9789451224e6df8d1d7ac63854c2f1beb30fa35d13ea06fbae9ba2b1b0a7f" + }, + "flutter-implement-json-serialization": { + "source": "flutter/skills", + "sourceType": "github", + "skillPath": "skills/flutter-implement-json-serialization/SKILL.md", + "computedHash": "c2cf46854472a452dafa11f862f2bca3d9fe7286a5bb45d85b1efbcebc74b74e" + }, + "flutter-setup-declarative-routing": { + "source": "flutter/skills", + "sourceType": "github", + "skillPath": "skills/flutter-setup-declarative-routing/SKILL.md", + "computedHash": "4c2ed2fd729230be581b15d84741688e206632fb2b38af320060cd3518b91179" + }, + "flutter-setup-localization": { + "source": "flutter/skills", + "sourceType": "github", + "skillPath": "skills/flutter-setup-localization/SKILL.md", + "computedHash": "fc0811b1b775c52c1b8f7df600f5c52b83029aea0586b8cc55169812affd408f" + }, + "flutter-use-http-package": { + "source": "flutter/skills", + "sourceType": "github", + "skillPath": "skills/flutter-use-http-package/SKILL.md", + "computedHash": "bd169b5cee731751f3b32f43c94cfe9495fc8e6c3eb621b785c69e38b77d0e19" + } + } +} diff --git a/windows/flutter/generated_plugin_registrant.cc b/windows/flutter/generated_plugin_registrant.cc index fd227d4..b6e481b 100644 --- a/windows/flutter/generated_plugin_registrant.cc +++ b/windows/flutter/generated_plugin_registrant.cc @@ -8,10 +8,13 @@ #include #include +#include void RegisterPlugins(flutter::PluginRegistry* registry) { AudioplayersWindowsPluginRegisterWithRegistrar( registry->GetRegistrarForPlugin("AudioplayersWindowsPlugin")); MmkvWin32PluginRegisterWithRegistrar( registry->GetRegistrarForPlugin("MmkvWin32Plugin")); + PermissionHandlerWindowsPluginRegisterWithRegistrar( + registry->GetRegistrarForPlugin("PermissionHandlerWindowsPlugin")); } diff --git a/windows/flutter/generated_plugins.cmake b/windows/flutter/generated_plugins.cmake index f1d64b0..44e8bc5 100644 --- a/windows/flutter/generated_plugins.cmake +++ b/windows/flutter/generated_plugins.cmake @@ -5,6 +5,7 @@ list(APPEND FLUTTER_PLUGIN_LIST audioplayers_windows mmkv_win32 + permission_handler_windows ) list(APPEND FLUTTER_FFI_PLUGIN_LIST From dc058777800bb6959c0b39ad5e8c18d89a583baa Mon Sep 17 00:00:00 2001 From: Merack Date: Sat, 30 May 2026 13:47:33 +0800 Subject: [PATCH 2/5] ci: fix aliyun mirror 502 on CI, rename apk & upload to R2 --- .github/workflows/dev.yml | 29 ++++++++++++++++++++++++++--- .github/workflows/release.yml | 26 ++++++++++++++++++++++++-- android/build.gradle.kts | 7 +++++-- android/settings.gradle.kts | 8 ++++++-- 4 files changed, 61 insertions(+), 9 deletions(-) diff --git a/.github/workflows/dev.yml b/.github/workflows/dev.yml index 97e4efa..e5665b3 100644 --- a/.github/workflows/dev.yml +++ b/.github/workflows/dev.yml @@ -42,6 +42,13 @@ jobs: - name: Build APKs (split by ABI) run: flutter build apk --release --split-per-abi + - name: Rename APKs + run: | + mkdir -p dist + cp build/app/outputs/flutter-apk/app-armeabi-v7a-release.apk dist/time_machine-armeabi-v7a-dev.apk + cp build/app/outputs/flutter-apk/app-arm64-v8a-release.apk dist/time_machine-arm64-v8a-dev.apk + cp build/app/outputs/flutter-apk/app-x86_64-release.apk dist/time_machine-x86_64-dev.apk + - name: Get commit info id: commit run: | @@ -60,18 +67,34 @@ jobs: with: to: ${{ secrets.TELEGRAM_TO }} token: ${{ secrets.TELEGRAM_TOKEN }} - document: build/app/outputs/flutter-apk/app-armeabi-v7a-release.apk + document: dist/time_machine-armeabi-v7a-dev.apk - name: Send arm64-v8a APK uses: appleboy/telegram-action@master with: to: ${{ secrets.TELEGRAM_TO }} token: ${{ secrets.TELEGRAM_TOKEN }} - document: build/app/outputs/flutter-apk/app-arm64-v8a-release.apk + document: dist/time_machine-arm64-v8a-dev.apk - name: Send x86_64 APK uses: appleboy/telegram-action@master with: to: ${{ secrets.TELEGRAM_TO }} token: ${{ secrets.TELEGRAM_TOKEN }} - document: build/app/outputs/flutter-apk/app-x86_64-release.apk + document: dist/time_machine-x86_64-dev.apk + + - name: Upload to Cloudflare R2 + env: + AWS_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }} + AWS_DEFAULT_REGION: auto + AWS_EC2_METADATA_DISABLED: "true" + # 关闭 aws-cli v2 默认的完整性校验,避免 R2 拒绝带 checksum 头的请求 + AWS_REQUEST_CHECKSUM_CALCULATION: when_required + AWS_RESPONSE_CHECKSUM_VALIDATION: when_required + run: | + for f in time_machine-arm64-v8a-dev.apk time_machine-x86_64-dev.apk; do + aws s3 cp "dist/$f" \ + "s3://${{ secrets.R2_BUCKET }}/time_machine/$f" \ + --endpoint-url "${{ secrets.R2_ENDPOINT }}" + done diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 93b9138..6a4a988 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -46,6 +46,12 @@ jobs: - name: Build APKs (split by ABI) run: flutter build apk --release --split-per-abi + - name: Rename APKs + run: | + mkdir -p dist + cp build/app/outputs/flutter-apk/app-arm64-v8a-release.apk dist/time_machine-arm64-v8a.apk + cp build/app/outputs/flutter-apk/app-x86_64-release.apk dist/time_machine-x86_64.apk + - name: Extract tag notes id: tag_notes run: | @@ -59,7 +65,23 @@ jobs: with: body: ${{ steps.tag_notes.outputs.notes }} files: | - build/app/outputs/flutter-apk/app-arm64-v8a-release.apk - build/app/outputs/flutter-apk/app-x86_64-release.apk + dist/time_machine-arm64-v8a.apk + dist/time_machine-x86_64.apk env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Upload to Cloudflare R2 + env: + AWS_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }} + AWS_DEFAULT_REGION: auto + AWS_EC2_METADATA_DISABLED: "true" + # 关闭 aws-cli v2 默认的完整性校验,避免 R2 拒绝带 checksum 头的请求 + AWS_REQUEST_CHECKSUM_CALCULATION: when_required + AWS_RESPONSE_CHECKSUM_VALIDATION: when_required + run: | + for f in time_machine-arm64-v8a.apk time_machine-x86_64.apk; do + aws s3 cp "dist/$f" \ + "s3://${{ secrets.R2_BUCKET }}/time_machine/$f" \ + --endpoint-url "${{ secrets.R2_ENDPOINT }}" + done diff --git a/android/build.gradle.kts b/android/build.gradle.kts index b8623bb..67ee8b8 100644 --- a/android/build.gradle.kts +++ b/android/build.gradle.kts @@ -1,8 +1,11 @@ allprojects { repositories { mavenLocal() - maven(url = "https://maven.aliyun.com/repository/public") - maven(url = "https://maven.aliyun.com/repository/google") + // 仅本地启用阿里云镜像加速;CI 直连官方源,避免镜像 502 拖垮构建 + if (System.getenv("CI") == null) { + maven(url = "https://maven.aliyun.com/repository/public") + maven(url = "https://maven.aliyun.com/repository/google") + } google() mavenCentral() diff --git a/android/settings.gradle.kts b/android/settings.gradle.kts index 8fb1a50..1eb2cd2 100644 --- a/android/settings.gradle.kts +++ b/android/settings.gradle.kts @@ -11,8 +11,12 @@ pluginManagement { repositories { mavenLocal() - maven(url = "https://maven.aliyun.com/repository/public") - maven(url = "https://maven.aliyun.com/repository/google") + // 仅本地启用阿里云镜像加速;CI(GitHub Actions 默认注入 CI=true)直连官方源, + // 避免镜像 502 时 Gradle 整体 disable 该仓库导致构建失败 + if (System.getenv("CI") == null) { + maven(url = "https://maven.aliyun.com/repository/public") + maven(url = "https://maven.aliyun.com/repository/google") + } google() mavenCentral() From 52f38cc9cc86d040a4ce85b16e4d81ffccbf8722 Mon Sep 17 00:00:00 2001 From: Merack Date: Sat, 30 May 2026 14:24:28 +0800 Subject: [PATCH 3/5] refactor: cleanup some old comment --- lib/database/backup_restore_db_service.dart | 12 +- lib/database/database_helper.dart | 17 -- lib/page/home/controller.dart | 230 +------------------- 3 files changed, 4 insertions(+), 255 deletions(-) diff --git a/lib/database/backup_restore_db_service.dart b/lib/database/backup_restore_db_service.dart index 21aa294..0b93187 100644 --- a/lib/database/backup_restore_db_service.dart +++ b/lib/database/backup_restore_db_service.dart @@ -52,11 +52,6 @@ class BackupRestoreDBService { // 创建与主数据库相同的表结构 await _createBackupTables(db); }, - // 更新: 直接删除整个数据库文件再重建, 性能可能会更好一点 - // 如果旧的备份文件已存在, 那么每次打开时都删除旧表 - // onOpen: (db) async { - // await _createBackupTables(db); - // }, ); // 将MMKV设置数据转移到settings表 @@ -239,8 +234,7 @@ class BackupRestoreDBService { /// 创建备份数据库表结构 Future _createBackupTables(Database db) async { - // 先删除已存在的表，然后创建focus_sessions表(更新: 直接删除整个数据库文件再重建, 性能可能会更好一点) - // await db.execute('DROP TABLE IF EXISTS ${DatabaseHelper.tableFocusSessions}'); + await db.execute(''' CREATE TABLE ${DatabaseHelper.tableFocusSessions} ( ${DatabaseHelper.columnId} INTEGER PRIMARY KEY AUTOINCREMENT, @@ -253,9 +247,7 @@ class BackupRestoreDBService { ${DatabaseHelper.columnSessionMode} TEXT ) '''); - - // 先删除已存在的表，然后创建settings表 (更新: 直接删除整个数据库文件重建, 性能可能会更好一点) - // await db.execute('DROP TABLE IF EXISTS ${DatabaseHelper.tableSettings}'); + await db.execute(''' CREATE TABLE ${DatabaseHelper.tableSettings} ( ${DatabaseHelper.columnSettingId} INTEGER PRIMARY KEY AUTOINCREMENT, diff --git a/lib/database/database_helper.dart b/lib/database/database_helper.dart index e14433b..8716bf4 100644 --- a/lib/database/database_helper.dart +++ b/lib/database/database_helper.dart @@ -76,17 +76,6 @@ class DatabaseHelper { ) '''); - // 创建settings表 - // await db.execute(''' - // CREATE TABLE $tableSettings ( - // $columnSettingId INTEGER PRIMARY KEY AUTOINCREMENT, - // $columnSettingKey TEXT NOT NULL UNIQUE, - // $columnSettingValue TEXT NOT NULL, - // $columnSettingType TEXT NOT NULL, - // $columnSettingCreatedAt INTEGER NOT NULL - // ) - // '''); - // 创建focus_sessions表索引以优化查询性能 await db.execute(''' CREATE INDEX idx_focus_sessions_start_time @@ -103,12 +92,6 @@ class DatabaseHelper { ON $tableFocusSessions ($columnStartTime, $columnEndTime) '''); - // 创建settings表索引 - // await db.execute(''' - // CREATE INDEX idx_settings_key - // ON $tableSettings ($columnSettingKey) - // '''); - Get.log('数据库表创建成功'); } catch (e) { Get.log('创建表失败: $e'); diff --git a/lib/page/home/controller.dart b/lib/page/home/controller.dart index 74d01ec..97a9fe3 100644 --- a/lib/page/home/controller.dart +++ b/lib/page/home/controller.dart @@ -14,11 +14,9 @@ import 'state.dart'; class HomeController extends GetxController { final HomeState state = HomeState(); final AudioPlayer _audioPlayer = AudioPlayer(); - // 计时放在后台isolate里, 这里用不上了, 留着参考 - // Timer? _timer; - // Timer? _microBreakTimer; + late final MMKV _storage; - // late final BackgroundTimerService _backgroundTimerService; + final FlutterBackgroundService _backgroundService = FlutterBackgroundService(); // 当前专注会话记录 @@ -35,8 +33,6 @@ class HomeController extends GetxController { @override void onClose() { - // _timer?.cancel(); - // _microBreakTimer?.cancel(); _audioPlayer.dispose(); super.onClose(); } @@ -163,26 +159,6 @@ class HomeController extends GetxController { } } - /// 重置计时器 (未保活版, 用不上了, 留着参考) - // void resetTimer() { - // // _playButtonSound(); - // - // // 停止后台计时器服务 - // // _backgroundTimerService.resetTimer(); - // - // // 清空当前会话信息（未完成的专注不记录） - // _currentSessionStartTime = null; - // - // _timer?.cancel(); - // _microBreakTimer?.cancel(); - // - // state.timerStatus.value = TimerStatus.stopped; - // state.remainingFocusTime.value = state.focusTimeSeconds.value; - // state.totalTime.value = state.focusTimeSeconds.value; - // state.isRunning.value = false; - // state.generateNextMicroBreakInterval(); - // } - /// 重置计时器(new) void resetTimer() { // _playButtonSound(); @@ -203,33 +179,6 @@ class HomeController extends GetxController { state.generateNextMicroBreakInterval(); } - /// 开始计时器 (未保活版, 用不上了, 留着参考) - // void _startTimer() { - // if (state.timerStatus.value == TimerStatus.stopped) { - // // 首次启动,进入专注状态 - // _startFocusSession(); - // } else { - // // 从暂停状态恢复 - // if (state.timerStatus.value == TimerStatus.paused) { - // // 更新 isRunning 状态 - // state.isRunning.value = true; - // // 如果之前的状态是 focus 或者 microBreak, 则恢复为专注状态 - // if ((state.previousStatus.value == TimerStatus.focus) || - // (state.previousStatus.value == TimerStatus.microBreak)) { - // state.timerStatus.value = TimerStatus.focus; - // } else { - // // 恢复为之前的状态, 逻辑上这里应该只能是 bigBreak - // state.timerStatus.value = state.previousStatus.value; - // } - // // 重新开始专注计时器 - // _startFocusCountdown(); - // // 重新生成随机间隔 - // state.generateNextMicroBreakInterval(); - // // 重新开始微休息计时器 - // _startMicroBreakCountdown(); - // } - // } - // } /// 开始计时器(new) Future _startTimer() async { bool isBackgroundServiceRunning = await _backgroundService.isRunning(); @@ -270,16 +219,6 @@ class HomeController extends GetxController { } } - /// 暂停计时器 (未保活版, 用不上了, 留着参考) - // void _pauseTimer() { - // // 一同暂停专注和微休息 - // _timer?.cancel(); - // _microBreakTimer?.cancel(); - // state.previousStatus.value = state.timerStatus.value; - // state.timerStatus.value = TimerStatus.paused; - // state.isRunning.value = false; - // } - /// 暂停计时器 (new) Future _pauseTimer() async { try { @@ -330,22 +269,8 @@ class HomeController extends GetxController { }); } - // 保留原有的前台计时器作为备用 - // _startFocusCountdown(); - // _startMicroBreakCountdown(); } - /// 开始倒计时(未保活版, 用不上, 留着参考) - // void _startFocusCountdown() { - // _timer = Timer.periodic(const Duration(seconds: 1), (timer) { - // if (state.remainingFocusTime.value > 0) { - // state.remainingFocusTime.value--; - // } else { - // _handleFocusTimerComplete(); - // } - // }); - // } - /// 检查是否启用微休息 bool checkIsEnabledMicroBreak() { Get.log("检查是否启用微休息: "); @@ -358,42 +283,6 @@ class HomeController extends GetxController { } } - /// 处理微休息到来时间和微休息期间倒计时 (未保活版, 用不上, 留着参考) - // void _startMicroBreakCountdown() { - // // 检查微休息是否启用 - // if (!state.microBreakEnabled.value) { - // return; - // } - // - // // 不启用微休息的逻辑 - // if (state.microBreakTimeSeconds.value == 0) { - // return; - // } - // // 处理微休息到来时间倒计时 - // if (state.timerStatus.value == TimerStatus.focus) { - // _microBreakTimer = Timer.periodic(const Duration(seconds: 1), (timer) { - // if (state.nextMicroBreakTime.value > 0) { - // state.nextMicroBreakTime.value--; - // Get.log("距离微休息开始还有: ${state.nextMicroBreakTime.value}"); - // } else { - // _handleMicroBreakStatus(isStartMicroBreak: true); - // } - // }); - // } - // // 处理微休息期间倒计时 - // if (state.timerStatus.value == TimerStatus.microBreak) { - // _microBreakTimer = Timer.periodic(const Duration(seconds: 1), (timer) { - // if (state.remainingMicroBreakTime.value > 0) { - // state.remainingMicroBreakTime.value--; - // Get.log("微休息时间还剩有: ${state.remainingMicroBreakTime.value}"); - // } else { - // Get.log("微休息完成"); - // _handleMicroBreakStatus(isStartMicroBreak: false); - // } - // }); - // } - // } - /// 微休息开始处理函数 void _handleMicroBreakStart() { Get.log("微休息开始"); @@ -430,60 +319,6 @@ class HomeController extends GetxController { }); } - /// 处理微休息的开始和结束 (未保活版, 用不上, 留着参考) - // void _handleMicroBreakStatus({required bool isStartMicroBreak}) { - // Get.log("微休息开始"); - // // 开始微休息 - // if (isStartMicroBreak) { - // _microBreakTimer?.cancel(); - // - // // 播放微休息开始音效 - // _playAudio('audio/drop.mp3'); - // - // // 进入微休息状态 - // state.timerStatus.value = TimerStatus.microBreak; - // - // // 开始微休息倒计时 - // // 设置微休息时间 - // state.remainingMicroBreakTime.value = state.microBreakTimeSeconds.value; - // _startMicroBreakCountdown(); - // } else { - // // 微休息结束 - // Get.log("微休息结束"); - // _microBreakTimer?.cancel(); - // - // // 播放微休息结束音效 - // _playAudio('audio/ding.mp3'); - // - // // 更新状态 - // state.timerStatus.value = TimerStatus.focus; - // - // state.generateNextMicroBreakInterval(); - // // 开始微休息倒计时 - // _startMicroBreakCountdown(); - // } - // } - - /// 处理计时器完成 (未保活版, 用不上了, 留着参考) - // void _handleFocusTimerComplete() { - // _timer?.cancel(); - // - // switch (state.timerStatus.value) { - // case TimerStatus.focus: - // _completeFocusStatus(); - // break; - // // 如果专注计时走完正好又处于微休息期间时, 仍然认为完成了专注任务 - // case TimerStatus.microBreak: - // _completeFocusStatus(); - // break; - // case TimerStatus.bigBreak: - // _completeBigBreak(); - // break; - // default: - // break; - // } - // } - /// 处理计时器完成(new) void _handleFocusTimerComplete() { switch (state.timerStatus.value) { @@ -509,42 +344,6 @@ class HomeController extends GetxController { } } - /// 完成专注状态倒计时 (未保活版, 用不上了, 留着参考) - // void _completeFocusStatus() { - // // 不在专注时段, 微休息停止计时 - // _microBreakTimer?.cancel(); - // - // // 记录专注会话完成 - // _recordFocusSession(); - // - // // 播放专注完成音效 - // _playAudio('audio/wakeup.mp3'); - // - // // 增加完成周期数 - // state.completedCycles.value++; - // - // // 如果用户设置大休息时间为0, 则跳过休息阶段 - // if (state.bigBreakTimeSeconds.value == 0) { - // if (state.autoStartNextFocus.value) { - // // 直接开始下一轮专注 - // resetTimer(); - // _startFocusSession(); - // } else { - // // 仅重置计时器, 保持停止状态 - // resetTimer(); - // } - // // 直接return 这个函数 - // return; - // } - // - // // 进入大休息状态 - // state.timerStatus.value = TimerStatus.bigBreak; - // state.remainingFocusTime.value = state.bigBreakTimeSeconds.value; - // state.totalTime.value = state.bigBreakTimeSeconds.value; - // - // // 开始大休息倒计时 - // _startFocusCountdown(); - // } /// 完成专注状态倒计时(new) void _completeFocusStatus() { // 不在专注时段, 微休息停止计时 @@ -643,31 +442,6 @@ class HomeController extends GetxController { } } - /// 跳过当前阶段（仅在debug模式下可用）(未保活版, 用不上了, 留着参考) - // void skipCurrentPhase() { - // // 播放按钮音效 - // _playAudio('audio/button.wav'); - // - // // 立即结束当前阶段 - // _timer?.cancel(); - // _microBreakTimer?.cancel(); - // - // switch (state.timerStatus.value) { - // case TimerStatus.focus: - // _completeFocusStatus(); - // break; - // case TimerStatus.microBreak: - // // _completeMicroBreak(); - // _startFocusCountdown(); - // _handleMicroBreakStatus(isStartMicroBreak: false); - // break; - // case TimerStatus.bigBreak: - // _completeBigBreak(); - // break; - // default: - // break; - // } - // } /// 跳过当前阶段（仅在debug模式下可用）(new) void skipCurrentPhase() { // 播放按钮音效 From f418fdd6b0ac0ffe2a91aab5c51813c0172f6f79 Mon Sep 17 00:00:00 2001 From: Merack Date: Sat, 30 May 2026 14:32:00 +0800 Subject: [PATCH 4/5] build: update dependencies --- linux/flutter/generated_plugins.cmake | 1 + pubspec.lock | 204 +++++++++++++----------- pubspec.yaml | 8 +- windows/flutter/generated_plugins.cmake | 1 + 4 files changed, 120 insertions(+), 94 deletions(-) diff --git a/linux/flutter/generated_plugins.cmake b/linux/flutter/generated_plugins.cmake index 6a33498..a0dab0b 100644 --- a/linux/flutter/generated_plugins.cmake +++ b/linux/flutter/generated_plugins.cmake @@ -8,6 +8,7 @@ list(APPEND FLUTTER_PLUGIN_LIST ) list(APPEND FLUTTER_FFI_PLUGIN_LIST + jni ) set(PLUGIN_BUNDLED_LIBRARIES) diff --git a/pubspec.lock b/pubspec.lock index 9367b85..7d1c77f 100644 --- a/pubspec.lock +++ b/pubspec.lock @@ -21,18 +21,18 @@ packages: dependency: transitive description: name: async - sha256: "758e6d74e971c3e5aceb4110bfd6698efc7f501675bcfe0c775459a8140750eb" + sha256: e2eb0491ba5ddb6177742d2da23904574082139b07c1e33b8503b9f46f3e1a37 url: "https://pub.flutter-io.cn" source: hosted - version: "2.13.0" + version: "2.13.1" audioplayers: dependency: "direct main" description: name: audioplayers - sha256: "5441fa0ceb8807a5ad701199806510e56afde2b4913d9d17c2f19f2902cf0ae4" + sha256: "1d0c1b1f2095e59080e2d5046639096417a86687d89778da41b0c9a06d683dfd" url: "https://pub.flutter-io.cn" source: hosted - version: "6.5.1" + version: "6.7.0" audioplayers_android: dependency: transitive description: @@ -45,10 +45,10 @@ packages: dependency: transitive description: name: audioplayers_darwin - sha256: "0811d6924904ca13f9ef90d19081e4a87f7297ddc19fc3d31f60af1aaafee333" + sha256: c994b3bb3a921e4904ac40e013fbc94488e824fd7c1de6326f549943b0b44a91 url: "https://pub.flutter-io.cn" source: hosted - version: "6.3.0" + version: "6.4.0" audioplayers_linux: dependency: transitive description: @@ -69,18 +69,18 @@ packages: dependency: transitive description: name: audioplayers_web - sha256: "1c0f17cec68455556775f1e50ca85c40c05c714a99c5eb1d2d57cc17ba5522d7" + sha256: "24a6f258062bd7da8cb2157e83fccb9816a08dd306cbaaa24f9813d071470545" url: "https://pub.flutter-io.cn" source: hosted - version: "5.1.1" + version: "5.2.1" audioplayers_windows: dependency: transitive description: name: audioplayers_windows - sha256: "4048797865105b26d47628e6abb49231ea5de84884160229251f37dfcbe52fd7" + sha256: "95f875a96c88c3dbbcb608d4f8288e300b0113d256a81d0b3197fcc18f0dc91a" url: "https://pub.flutter-io.cn" source: hosted - version: "4.2.1" + version: "4.3.1" boolean_selector: dependency: transitive description: @@ -125,10 +125,10 @@ packages: dependency: transitive description: name: code_assets - sha256: "83ccdaa064c980b5596c35dd64a8d3ecc68620174ab9b90b6343b753aa721687" + sha256: "67cf6d84013f9c601e42a6f8a6b74c4c0d9dc1a1619d775f2b28b732d3551b85" url: "https://pub.flutter-io.cn" source: hosted - version: "1.0.0" + version: "1.2.0" collection: dependency: transitive description: @@ -157,10 +157,10 @@ packages: dependency: "direct main" description: name: cupertino_icons - sha256: ba631d1c7f7bef6b729a622b7b752645a2d076dba9976925b8f25725a30e1ee6 + sha256: "41e005c33bd814be4d3096aff55b1908d419fde52ca656c8c47719ec745873cd" url: "https://pub.flutter-io.cn" source: hosted - version: "1.0.8" + version: "1.0.9" dbus: dependency: transitive description: @@ -173,18 +173,18 @@ packages: dependency: "direct main" description: name: device_info_plus - sha256: "4df8babf73058181227e18b08e6ea3520cf5fc5d796888d33b7cb0f33f984b7c" + sha256: "6a642e1daa10190af89ba6cb6386c0df7d071a3592080bfe1e44faa63ae1df65" url: "https://pub.flutter-io.cn" source: hosted - version: "12.3.0" + version: "13.1.0" device_info_plus_platform_interface: dependency: transitive description: name: device_info_plus_platform_interface - sha256: e1ea89119e34903dca74b883d0dd78eb762814f97fb6c76f35e9ff74d261a18f + sha256: "04b173a92e2d9161dfead145667037c8d834db725ce2e7b942bfe18fd2f45a46" url: "https://pub.flutter-io.cn" source: hosted - version: "7.0.3" + version: "8.1.0" fake_async: dependency: transitive description: @@ -201,6 +201,14 @@ packages: url: "https://pub.flutter-io.cn" source: hosted version: "2.2.0" + ffi_leak_tracker: + dependency: transitive + description: + name: ffi_leak_tracker + sha256: "4093d4ef9ca06ffe2786e73bfb25e22aa92112b9bb4ec941f11e3e6b61489a97" + url: "https://pub.flutter-io.cn" + source: hosted + version: "0.1.2" file: dependency: transitive description: @@ -213,10 +221,10 @@ packages: dependency: "direct main" description: name: file_picker - sha256: "57d9a1dd5063f85fa3107fb42d1faffda52fdc948cefd5fe5ea85267a5fc7343" + sha256: fc83774ce5bd7ce08168333b5e53dbe9090ec04eb21e7aa7cd7bac921032c934 url: "https://pub.flutter-io.cn" source: hosted - version: "10.3.10" + version: "12.0.0-beta.5" fixnum: dependency: transitive description: @@ -282,42 +290,42 @@ packages: dependency: "direct main" description: name: flutter_local_notifications - sha256: "2b50e938a275e1ad77352d6a25e25770f4130baa61eaf02de7a9a884680954ad" + sha256: "0d9035862236fe38250fe1644d7ed3b8254e34a21b2c837c9f539fbb3bba5ef1" url: "https://pub.flutter-io.cn" source: hosted - version: "20.1.0" + version: "21.0.0" flutter_local_notifications_linux: dependency: transitive description: name: flutter_local_notifications_linux - sha256: dce0116868cedd2cdf768af0365fc37ff1cbef7c02c4f51d0587482e625868d0 + sha256: e0f25e243c6c44c825bbbc6b2b2e76f7d9222362adcfe9fd780bf01923c840bd url: "https://pub.flutter-io.cn" source: hosted - version: "7.0.0" + version: "8.0.0" flutter_local_notifications_platform_interface: dependency: transitive description: name: flutter_local_notifications_platform_interface - sha256: "23de31678a48c084169d7ae95866df9de5c9d2a44be3e5915a2ff067aeeba899" + sha256: e7db3d5b49c2b7ecc68deba4aaaa67a348f92ee0fef34c8e4b4459dbef0d7307 url: "https://pub.flutter-io.cn" source: hosted - version: "10.0.0" + version: "11.0.0" flutter_local_notifications_windows: dependency: transitive description: name: flutter_local_notifications_windows - sha256: e97a1a3016512437d9c0b12fae7d1491c3c7b9aa7f03a69b974308840656b02a + sha256: "3a2654ba104fbb52c618ebed9def24ef270228470718c43b3a6afcd5c81bef0c" url: "https://pub.flutter-io.cn" source: hosted - version: "2.0.1" + version: "3.0.0" flutter_plugin_android_lifecycle: dependency: transitive description: name: flutter_plugin_android_lifecycle - sha256: ee8068e0e1cd16c4a82714119918efdeed33b3ba7772c54b5d094ab53f9b7fd1 + sha256: "38d1c268de9097ff59cf0e844ac38759fc78f76836d37edad06fa21e182055a0" url: "https://pub.flutter-io.cn" source: hosted - version: "2.0.33" + version: "2.0.34" flutter_test: dependency: "direct dev" description: flutter @@ -336,22 +344,14 @@ packages: url: "https://pub.flutter-io.cn" source: hosted version: "4.7.3" - glob: - dependency: transitive - description: - name: glob - sha256: c3f1ee72c96f8f78935e18aa8cecced9ab132419e8625dc187e1c2408efc20de - url: "https://pub.flutter-io.cn" - source: hosted - version: "2.1.3" hooks: dependency: transitive description: name: hooks - sha256: "7a08a0d684cb3b8fb604b78455d5d352f502b68079f7b80b831c62220ab0a4f6" + sha256: a41af4e8fc687cd6d33de9751eb936c8c0204ebe2bcb6c15ecf707504bf47f31 url: "https://pub.flutter-io.cn" source: hosted - version: "1.0.1" + version: "2.0.0" http: dependency: transitive description: @@ -376,14 +376,30 @@ packages: url: "https://pub.flutter-io.cn" source: hosted version: "4.8.0" + jni: + dependency: transitive + description: + name: jni + sha256: c2230682d5bc2362c1c9e8d3c7f406d9cbba23ab3f2e203a025dd47e0fb2e68f + url: "https://pub.flutter-io.cn" + source: hosted + version: "1.0.0" + jni_flutter: + dependency: transitive + description: + name: jni_flutter + sha256: "8b59e590786050b1cd866677dddaf76b1ade5e7bc751abe04b86e84d379d3ba6" + url: "https://pub.flutter-io.cn" + source: hosted + version: "1.0.1" json_annotation: dependency: transitive description: name: json_annotation - sha256: cb09e7dac6210041fad964ed7fbee004f14258b4eca4040f72d1234062ace4c8 + sha256: "2a743920d81b7910627f68ee2c9ac1fc0bfee32b9fc3403587d7c6791ca12f80" url: "https://pub.flutter-io.cn" source: hosted - version: "4.11.0" + version: "4.12.0" leak_tracker: dependency: transitive description: @@ -452,90 +468,90 @@ packages: dependency: "direct main" description: name: mmkv - sha256: "3299a7fa095139471ffd8ab40d5f8d2fb48c2d881c42fbca769ccb7520058fbb" + sha256: "42fb1a6be1b00051612b4060e343eb28ade355ef6b845b07351696b2c6d2b256" url: "https://pub.flutter-io.cn" source: hosted - version: "2.3.0" + version: "2.4.0" mmkv_android: dependency: transitive description: name: mmkv_android - sha256: e831636319d6e343a011a07bffb61af5e8182a4924f1c01fc75c1da30b30cee4 + sha256: "1cf400ea4527306fcbe9db962441d8fe347cfad1dfd8034b4f465c5d501dc40d" url: "https://pub.flutter-io.cn" source: hosted - version: "2.3.0" + version: "2.4.0" mmkv_ios: dependency: transitive description: name: mmkv_ios - sha256: b97f331193cfb95f91d9e62ea0fe3f0b4d457b9416bcd20408979b024d67c893 + sha256: ee97fd5c1d7941fc4a5a60f68c08b505d9257a22b10081a90aa3325fd782da18 url: "https://pub.flutter-io.cn" source: hosted - version: "2.3.0" + version: "2.4.0" mmkv_linux: dependency: transitive description: name: mmkv_linux - sha256: "3fa97cc3b63f66e602c722cbca717f5259b3234b3db3bb325cc9010d76426ad2" + sha256: a8f66b18c673d56c62abf7e7097d2d5b760f8e10afc5ff01f02f4e91683b3dcf url: "https://pub.flutter-io.cn" source: hosted - version: "2.3.0" + version: "2.4.0" mmkv_ohos: dependency: transitive description: name: mmkv_ohos - sha256: "4dc5d7d93e64488e60dc1d92462ab75f90ebbc3827a06f525a326140936ff31f" + sha256: "3477f5f9233ed6e5929e75bee9273f7835de576d637fedd6a72572bb230b72b5" url: "https://pub.flutter-io.cn" source: hosted - version: "2.3.0" + version: "2.4.0" mmkv_platform_interface: dependency: transitive description: name: mmkv_platform_interface - sha256: cb6deafaeb31ed9d9dccdf6cd37f5f5be47424662d8e967fdbb1111f04cadac7 + sha256: bef7422b14f84297fe637adc82b9fe018155a429fcbaef53efb06ecf005b0288 url: "https://pub.flutter-io.cn" source: hosted - version: "2.3.0" + version: "2.4.0" mmkv_win32: dependency: transitive description: name: mmkv_win32 - sha256: "09f7917e1b011d19194e94386ea47d5942963e3f4da573133981dd8f2bc17da3" + sha256: "34b8b8a4596a23bc375f4ea811fc7d81674a15a4961d58dd9b126b50168d41a8" url: "https://pub.flutter-io.cn" source: hosted - version: "2.3.0" - native_toolchain_c: + version: "2.4.0" + objective_c: dependency: transitive description: - name: native_toolchain_c - sha256: "89e83885ba09da5fdf2cdacc8002a712ca238c28b7f717910b34bcd27b0d03ac" + name: objective_c + sha256: "6cb691c686fa2838c6deb34980d426145c2a5d537491cb83d463c33cdbc726ed" url: "https://pub.flutter-io.cn" source: hosted - version: "0.17.4" - objective_c: + version: "9.4.1" + package_config: dependency: transitive description: - name: objective_c - sha256: "100a1c87616ab6ed41ec263b083c0ef3261ee6cd1dc3b0f35f8ddfa4f996fe52" + name: package_config + sha256: f096c55ebb7deb7e384101542bfba8c52696c1b56fca2eb62827989ef2353bbc url: "https://pub.flutter-io.cn" source: hosted - version: "9.3.0" + version: "2.2.0" package_info_plus: dependency: "direct main" description: name: package_info_plus - sha256: f69da0d3189a4b4ceaeb1a3defb0f329b3b352517f52bed4290f83d4f06bc08d + sha256: "4bf625947f6c7713ee242296a682e23e44823c09cf9d79e4f1238923c92db852" url: "https://pub.flutter-io.cn" source: hosted - version: "9.0.0" + version: "10.1.0" package_info_plus_platform_interface: dependency: transitive description: name: package_info_plus_platform_interface - sha256: "202a487f08836a592a6bd4f901ac69b3a8f146af552bbd14407b6b41e1c3f086" + sha256: db762cb2f4f25ee60fb6359773861b0f199e00b90d237bd85a76a1e806b46ef4 url: "https://pub.flutter-io.cn" source: hosted - version: "3.2.1" + version: "4.1.0" path: dependency: "direct main" description: @@ -556,10 +572,10 @@ packages: dependency: transitive description: name: path_provider_android - sha256: f2c65e21139ce2c3dad46922be8272bb5963516045659e71bb16e151c93b580e + sha256: "69cbd515a62b94d32a7944f086b2f82b4ac40a1d45bebfc00813a430ab2dabcd" url: "https://pub.flutter-io.cn" source: hosted - version: "2.2.22" + version: "2.3.1" path_provider_foundation: dependency: transitive description: @@ -596,10 +612,10 @@ packages: dependency: "direct main" description: name: permission_handler - sha256: bc917da36261b00137bbc8896bf1482169cd76f866282368948f032c8c1caae1 + sha256: ca045d03615023c08ccdb297aad46a9198193666039ddd36d4d85fd0b1864b98 url: "https://pub.flutter-io.cn" source: hosted - version: "12.0.1" + version: "12.0.2" permission_handler_android: dependency: transitive description: @@ -612,10 +628,10 @@ packages: dependency: transitive description: name: permission_handler_apple - sha256: f000131e755c54cf4d84a5d8bd6e4149e262cc31c5a8b1d698de1ac85fa41023 + sha256: "447c18bc3c5fdea5c3039f042b2b365fd51e3634f5f6e269ed22c1f00071addc" url: "https://pub.flutter-io.cn" source: hosted - version: "9.4.7" + version: "9.4.8" permission_handler_html: dependency: transitive description: @@ -680,6 +696,14 @@ packages: url: "https://pub.flutter-io.cn" source: hosted version: "2.2.0" + record_use: + dependency: transitive + description: + name: record_use + sha256: "2551bd8eecfe95d14ae75f6021ad0248be5c27f138c2ec12fcb52b500b3ba1ed" + url: "https://pub.flutter-io.cn" + source: hosted + version: "0.6.0" sky_engine: dependency: transitive description: flutter @@ -697,26 +721,26 @@ packages: dependency: "direct main" description: name: sqflite - sha256: e2297b1da52f127bc7a3da11439985d9b536f75070f3325e62ada69a5c585d03 + sha256: "564cfed0746fe53140c23b70b308e045c3b31f17778f2f326ccb7d804ea0250a" url: "https://pub.flutter-io.cn" source: hosted - version: "2.4.2" + version: "2.4.2+1" sqflite_android: dependency: transitive description: name: sqflite_android - sha256: ecd684501ebc2ae9a83536e8b15731642b9570dc8623e0073d227d0ee2bfea88 + sha256: "881e28efdcc9950fd8e9bb42713dcf1103e62a2e7168f23c9338d82db13dec40" url: "https://pub.flutter-io.cn" source: hosted - version: "2.4.2+2" + version: "2.4.2+3" sqflite_common: dependency: transitive description: name: sqflite_common - sha256: "6ef422a4525ecc601db6c0a2233ff448c731307906e92cabc9ba292afaae16a6" + sha256: "1581ffbf7a0e333b380d6a30737d78516b826cb35beb7fb0bf8a3ea0c678b465" url: "https://pub.flutter-io.cn" source: hosted - version: "2.5.6" + version: "2.5.8" sqflite_darwin: dependency: transitive description: @@ -761,10 +785,10 @@ packages: dependency: transitive description: name: synchronized - sha256: c254ade258ec8282947a0acbbc90b9575b4f19673533ee46f2f6e9b3aeefd7c0 + sha256: "63896c27e81b28f8cb4e69ead0d3e8f03f1d1e5fc531a3e579cabed6a2c7c9e5" url: "https://pub.flutter-io.cn" source: hosted - version: "3.4.0" + version: "3.4.0+1" term_glyph: dependency: transitive description: @@ -785,10 +809,10 @@ packages: dependency: transitive description: name: timezone - sha256: dd14a3b83cfd7cb19e7888f1cbc20f258b8d71b54c06f79ac585f14093a287d1 + sha256: "784a5e34d2eb62e1326f24d6f600aaaee452eb8ca8ef2f384a59244e292d158b" url: "https://pub.flutter-io.cn" source: hosted - version: "0.10.1" + version: "0.11.0" typed_data: dependency: transitive description: @@ -817,10 +841,10 @@ packages: dependency: transitive description: name: vm_service - sha256: "45caa6c5917fa127b5dbcfbd1fa60b14e583afdc08bfc96dda38886ca252eb60" + sha256: "0016aef94fc66495ac78af5859181e3f3bf2026bd8eecc72b9565601e19ab360" url: "https://pub.flutter-io.cn" source: hosted - version: "15.0.2" + version: "15.2.0" web: dependency: transitive description: @@ -833,18 +857,18 @@ packages: dependency: transitive description: name: win32 - sha256: d7cb55e04cd34096cd3a79b3330245f54cb96a370a1c27adb3c84b917de8b08e + sha256: ba6f4bba816c8d7e3c1580e170f3786d216951cc6b94babc3b814c08d2cb2738 url: "https://pub.flutter-io.cn" source: hosted - version: "5.15.0" + version: "6.3.0" win32_registry: dependency: transitive description: name: win32_registry - sha256: "6f1b564492d0147b330dd794fee8f512cec4977957f310f9951b5f9d83618dae" + sha256: "73b1d78920a9d6e03f8b4e43e612b87bf3152a0e5c5e5150267762b7c4116904" url: "https://pub.flutter-io.cn" source: hosted - version: "2.1.0" + version: "3.0.3" xdg_directories: dependency: transitive description: diff --git a/pubspec.yaml b/pubspec.yaml index 56a6532..094dfb0 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -37,10 +37,10 @@ dependencies: sqflite: ^2.4.2 path: ^1.9.1 flutter_background_service: ^5.1.0 - flutter_local_notifications: ^20.1.0 - device_info_plus: ^12.3.0 - package_info_plus: ^9.0.0 - file_picker: ^10.2.0 + flutter_local_notifications: ^21.0.0 + device_info_plus: ^13.1.0 + package_info_plus: ^10.1.0 + file_picker: ^12.0.0-beta.5 path_provider: ^2.1.5 permission_handler: ^12.0.0+1 diff --git a/windows/flutter/generated_plugins.cmake b/windows/flutter/generated_plugins.cmake index 44e8bc5..dd156c8 100644 --- a/windows/flutter/generated_plugins.cmake +++ b/windows/flutter/generated_plugins.cmake @@ -10,6 +10,7 @@ list(APPEND FLUTTER_PLUGIN_LIST list(APPEND FLUTTER_FFI_PLUGIN_LIST flutter_local_notifications_windows + jni ) set(PLUGIN_BUNDLED_LIBRARIES) From 55edb9756ca58f65d0604e7435c0b65d57033361 Mon Sep 17 00:00:00 2001 From: Merack Date: Sat, 30 May 2026 14:44:29 +0800 Subject: [PATCH 5/5] fix: new syntax for file_picker --- lib/database/backup_restore_db_service.dart | 2 +- lib/page/sound_settings/controller.dart | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/database/backup_restore_db_service.dart b/lib/database/backup_restore_db_service.dart index 0b93187..5783932 100644 --- a/lib/database/backup_restore_db_service.dart +++ b/lib/database/backup_restore_db_service.dart @@ -87,7 +87,7 @@ class BackupRestoreDBService { // Get.log('===${(await getDownloadsDirectory())?.path}==='); // 选择备份文件 - final result = await FilePicker.platform.pickFiles( + final result = await FilePicker.pickFiles( // 这里的FileType.custom无法识别db文件, 还是用默认的any吧, 只不过这样要自己验证后缀了 // TODO: 文件后缀验证 // type: FileType.custom, diff --git a/lib/page/sound_settings/controller.dart b/lib/page/sound_settings/controller.dart index 4a11784..7ad9016 100644 --- a/lib/page/sound_settings/controller.dart +++ b/lib/page/sound_settings/controller.dart @@ -140,7 +140,7 @@ class SoundSettingsController extends GetxController { return; } - final result = await FilePicker.platform.pickFiles( + final result = await FilePicker.pickFiles( type: FileType.audio, dialogTitle: '选择音频文件', );