sdd-full 4.6.2 → 4.8.1

package/skills/flutter/skills/flutter-implement-json-serialization/SKILL.md

@@ -0,0 +1,155 @@
+【claude code调用标识：flutter-implement-json-serialization】【trae调用标识：flutter-implement-json-serialization+Flutter开发】【流程场景：1.完整3阶段SDD流程、3.小型功能迭代】
+
+---
+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<String, dynamic>` for objects or `List<dynamic>` 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<String, dynamic> json)` constructor.
+- [ ] Implement the `Map<String, dynamic> 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<String, dynamic>` 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<String, dynamic> 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<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'name': name,
+      'email': email,
+    };
+  }
+}
+```
+
+### Synchronous Parsing (Small Payload)
+
+```dart
+import 'dart:convert';
+import 'package:http/http.dart' as http;
+
+Future<User> 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<String, dynamic>
+    final Map<String, dynamic> jsonMap = jsonDecode(response.body) as Map<String, dynamic>;
+    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<User> parseUsers(String responseBody) {
+  final parsed = (jsonDecode(responseBody) as List<dynamic>).cast<Map<String, dynamic>>();
+  return parsed.map<User>((json) => User.fromJson(json)).toList();
+}
+
+Future<List<User>> 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');
+  }
+}
+```

package/skills/flutter/skills/flutter-setup-declarative-routing/SKILL.md

@@ -0,0 +1,257 @@
+【claude code调用标识：flutter-setup-declarative-routing】【trae调用标识：flutter-setup-declarative-routing+Flutter开发】【流程场景：1.完整3阶段SDD流程、2.从零开始新项目】
+
+---
+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 <app-name>
+cd <app-name>
+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 `<activity>` tag for `.MainActivity`.
+```xml
+<intent-filter android:autoVerify="true">
+    <action android:name="android.intent.action.VIEW" />
+    <category android:name="android.intent.category.DEFAULT" />
+    <category android:name="android.intent.category.BROWSABLE" />
+    <data android:scheme="http" android:host="yourdomain.com" />
+    <data android:scheme="https" />
+</intent-filter>
+```
+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
+<key>FlutterDeepLinkingEnabled</key>
+<true/>
+```
+2. **Modify `Runner.entitlements`**: Add the associated domain.
+```xml
+<key>com.apple.developer.associated-domains</key>
+<array>
+  <string>applinks:yourdomain.com</string>
+</array>
+```
+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();
+```

package/skills/flutter/skills/flutter-setup-localization/SKILL.md

@@ -0,0 +1,212 @@
+【claude code调用标识：flutter-setup-localization】【trae调用标识：flutter-setup-localization+Flutter开发】【流程场景：1.完整3阶段SDD流程、3.小型功能迭代】
+
+---
+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)),
+      ],
+    );
+  }
+}
+```