feat: 增强 HomeScreen 录音交互与 ChatBloc 状态管理

- 新增录音启动延迟处理，解决权限未就绪时的竞态问题 - 实现历史分页滚动位置保持，提升加载体验 - 添加文本输入框点击键盘显示与焦点管理 - 优化 ChatBloc provider 到 MultiBlocProvider 支持 - 修复 ApiException 429 错误详情解析（支持 JSON 字符串 body） - 改进 LocalNotificationService 精确闹钟权限请求 - 优化 UiSchemaRenderer GridView children 生成 - 支持导航 action 的 replace 参数 - 移除 Agent router 速率限制逻辑（_allow_run_request, _allow_transcribe_request） - 补充相关单元测试与集成测试
2026-03-18 17:03:22 +08:00
parent b34697660d
commit 8539f05a66
13 changed files with 578 additions and 143 deletions
@@ -1,3 +1,5 @@
+import 'dart:convert';
+
 import 'package:dio/dio.dart';

 abstract class ApiException implements Exception {
@@ -17,9 +19,14 @@ abstract class ApiException implements Exception {
      final data = response?.data;

      String detail;
-      if (data is Map<String, dynamic>) {
+      final decodedData = _normalizeErrorData(data);
+
+      if (decodedData is Map<String, dynamic>) {
        detail =
-            (data['detail'] ?? data['message'] ?? data['error'])?.toString() ??
+            (decodedData['detail'] ??
+                    decodedData['message'] ??
+                    decodedData['error'])
+                ?.toString() ??
            '请求失败';
      } else {
        detail = _networkErrorMessage(error);
@@ -42,6 +49,29 @@ abstract class ApiException implements Exception {
    return const ServerException('网络错误');
  }

+  static Map<String, dynamic>? _normalizeErrorData(dynamic data) {
+    if (data is Map<String, dynamic>) {
+      return data;
+    }
+    if (data is Map) {
+      return data.map((key, value) => MapEntry(key.toString(), value));
+    }
+    if (data is String && data.trim().isNotEmpty) {
+      try {
+        final decoded = jsonDecode(data);
+        if (decoded is Map<String, dynamic>) {
+          return decoded;
+        }
+        if (decoded is Map) {
+          return decoded.map((key, value) => MapEntry(key.toString(), value));
+        }
+      } catch (_) {
+        return null;
+      }
+    }
+    return null;
+  }
+
  static String _localizeError(String detail, int? statusCode) {
    if (statusCode == 403) {
      return '没有权限执行此操作';
@@ -50,7 +80,11 @@ abstract class ApiException implements Exception {
      return '请求的资源不存在';
    }
    if (statusCode == 429) {
-      return '请求过于频繁，请稍后再试';
+      final normalized = detail.trim();
+      if (normalized.isEmpty || normalized == '请求失败') {
+        return '请求过于频繁，请稍后再试';
+      }
+      return detail;
    }
    if (statusCode != null && statusCode >= 500) {
      return '服务器错误，请稍后再试';
@@ -1,12 +1,23 @@
 import 'package:flutter_local_notifications/flutter_local_notifications.dart';
+import 'package:flutter/foundation.dart';
 import 'package:timezone/data/latest.dart' as tz_data;
 import 'package:timezone/timezone.dart' as tz;

 import '../../features/calendar/data/models/schedule_item_model.dart';

+class NotificationScheduleException implements Exception {
+  final String message;
+
+  NotificationScheduleException(this.message);
+
+  @override
+  String toString() => message;
+}
+
 class LocalNotificationService {
  final FlutterLocalNotificationsPlugin _plugin;
  bool _initialized = false;
+  bool _exactAlarmPermissionRequested = false;

  LocalNotificationService({FlutterLocalNotificationsPlugin? plugin})
    : _plugin = plugin ?? FlutterLocalNotificationsPlugin();
@@ -27,17 +38,17 @@ class LocalNotificationService {

    await _plugin.initialize(settings);

-    await _plugin
+    final androidImpl = _plugin
        .resolvePlatformSpecificImplementation<
          AndroidFlutterLocalNotificationsPlugin
-        >()
-        ?.requestNotificationsPermission();
+        >();
+    await androidImpl?.requestNotificationsPermission();

-    await _plugin
+    final iosImpl = _plugin
        .resolvePlatformSpecificImplementation<
          IOSFlutterLocalNotificationsPlugin
-        >()
-        ?.requestPermissions(alert: true, badge: true, sound: true);
+        >();
+    await iosImpl?.requestPermissions(alert: true, badge: true, sound: true);

    _initialized = true;
  }
@@ -59,6 +70,41 @@ class LocalNotificationService {

    final notificationId = _notificationIdForEvent(event.id);
    final scheduledAt = tz.TZDateTime.from(fireAt, tz.local);
+    final androidImpl = _plugin
+        .resolvePlatformSpecificImplementation<
+          AndroidFlutterLocalNotificationsPlugin
+        >();
+
+    var androidScheduleMode = AndroidScheduleMode.exactAllowWhileIdle;
+    if (defaultTargetPlatform == TargetPlatform.android &&
+        androidImpl != null) {
+      var notificationsEnabled =
+          await androidImpl.areNotificationsEnabled() ?? false;
+      if (!notificationsEnabled) {
+        await androidImpl.requestNotificationsPermission();
+        notificationsEnabled =
+            await androidImpl.areNotificationsEnabled() ?? false;
+      }
+      if (!notificationsEnabled) {
+        throw NotificationScheduleException('系统通知权限未开启，无法创建提醒');
+      }
+
+      try {
+        var canScheduleExact =
+            await androidImpl.canScheduleExactNotifications() ?? false;
+        if (!canScheduleExact && !_exactAlarmPermissionRequested) {
+          _exactAlarmPermissionRequested = true;
+          await androidImpl.requestExactAlarmsPermission();
+          canScheduleExact =
+              await androidImpl.canScheduleExactNotifications() ?? false;
+        }
+        if (!canScheduleExact) {
+          androidScheduleMode = AndroidScheduleMode.inexactAllowWhileIdle;
+        }
+      } catch (_) {
+        androidScheduleMode = AndroidScheduleMode.inexactAllowWhileIdle;
+      }
+    }

    final details = NotificationDetails(
      android: AndroidNotificationDetails(
@@ -83,11 +129,20 @@ class LocalNotificationService {
        _buildReminderBody(event, reminderMinutes),
        scheduledAt,
        details,
-        androidScheduleMode: AndroidScheduleMode.exactAllowWhileIdle,
+        androidScheduleMode: androidScheduleMode,
        uiLocalNotificationDateInterpretation:
            UILocalNotificationDateInterpretation.absoluteTime,
      );
-    } catch (_) {
+
+      final pending = await _plugin.pendingNotificationRequests();
+      final scheduled = pending.any((item) => item.id == notificationId);
+      if (!scheduled) {
+        throw NotificationScheduleException('提醒未被系统接受，请检查系统通知和电池优化设置');
+      }
+    } catch (error) {
+      if (error is NotificationScheduleException) {
+        rethrow;
+      }
      await _plugin.zonedSchedule(
        notificationId,
        event.title,
@@ -98,6 +153,12 @@ class LocalNotificationService {
        uiLocalNotificationDateInterpretation:
            UILocalNotificationDateInterpretation.absoluteTime,
      );
+
+      final pending = await _plugin.pendingNotificationRequests();
+      final scheduled = pending.any((item) => item.id == notificationId);
+      if (!scheduled) {
+        throw NotificationScheduleException('提醒创建失败，请检查系统设置后重试');
+      }
    }
  }

@@ -669,9 +669,9 @@ class _CreateEventSheetState extends State<CreateEventSheet>
      try {
        final notificationService = sl<LocalNotificationService>();
        await notificationService.upsertEventReminder(saved);
-      } catch (_) {
+      } catch (e) {
        if (mounted) {
-          Toast.show(context, '提醒创建失败，请检查通知权限', type: ToastType.warning);
+          Toast.show(context, '提醒创建失败：$e', type: ToastType.warning);
        }
      }

@@ -75,7 +75,6 @@ class UiSchemaRenderer {
    ).whereType<Map<String, dynamic>>().map(_renderNode).toList();
    final columns = _asInt(node['columns'], fallback: 2).clamp(1, 3);
    final gap = _asDouble(node['gap'], fallback: AppSpacing.sm);
-    final tiles = List.generate(children.length, (index) => children[index]);
    return _wrapSurface(
      node,
      GridView.count(
@@ -85,7 +84,7 @@ class UiSchemaRenderer {
        childAspectRatio: 1.6,
        physics: const NeverScrollableScrollPhysics(),
        shrinkWrap: true,
-        children: tiles,
+        children: children,
      ),
    );
  }
@@ -233,6 +232,7 @@ class UiSchemaRenderer {
    }

    final params = _asMap(action['params']);
+    final replace = action['replace'] == true;
    final queryParams = _extractNavigationQueryParams(params);
    try {
      final baseUri = Uri.parse(path);
@@ -240,7 +240,12 @@ class UiSchemaRenderer {
      final targetUri = baseUri.replace(
        queryParameters: mergedQueryParams.isEmpty ? null : mergedQueryParams,
      );
-      context.go(targetUri.toString());
+      final target = targetUri.toString();
+      if (replace) {
+        context.replace(target);
+        return;
+      }
+      context.push(target);
    } on FormatException {
      Toast.show(context, '导航路径无效', type: ToastType.warning);
    }
@@ -1,5 +1,6 @@
 import 'dart:io';

+import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
 import 'package:flutter_bloc/flutter_bloc.dart';
@@ -85,6 +86,7 @@ class HomeScreen extends StatefulWidget {
 class _HomeScreenState extends State<HomeScreen>
    with SingleTickerProviderStateMixin {
  final TextEditingController _messageController = TextEditingController();
+  final FocusNode _messageFocusNode = FocusNode();
  final ScrollController _scrollController = ScrollController();
  late final ChatBloc _chatBloc;
  late final VoiceRecorder _voiceRecorder;
@@ -92,20 +94,31 @@ class _HomeScreenState extends State<HomeScreen>
  late final Future<String> Function(String filePath) _transcribeAudio;
  late final AnimationController _listeningAnimationController;
  bool _isRecording = false;
+  bool _isRecordingStarting = false;
  bool _isHoldToSpeakMode = true;
  bool _isTranscribing = false;
  bool _isCancelGestureActive = false;
+  bool _shouldCancelWhenStartCompletes = false;
+  bool _shouldStopWhenStartCompletes = false;
  bool _isSendingMessage = false;
  bool _isPullRefreshing = false;
+  bool _isHistoryPaginationInFlight = false;
  int _unreadCount = 0;
  final List<XFile> _selectedImages = [];
  int _lastObservedItemCount = 0;
  bool _lastObservedWaiting = false;
+  double? _historyViewportPixels;
+  double? _historyViewportMaxExtent;

  @override
  void initState() {
    super.initState();
-    _chatBloc = widget.chatBloc ?? ChatBloc(apiClient: sl());
+    final providedChatBloc = widget.chatBloc;
+    if (providedChatBloc != null) {
+      _chatBloc = providedChatBloc;
+    } else {
+      _chatBloc = context.read<ChatBloc>();
+    }
    _voiceRecorder = widget.voiceRecorder ?? RecordVoiceRecorder();
    _inboxApi = sl<InboxApi>();
    _transcribeAudio =
@@ -137,12 +150,10 @@ class _HomeScreenState extends State<HomeScreen>
  @override
  void dispose() {
    _messageController.dispose();
+    _messageFocusNode.dispose();
    _scrollController.dispose();
    _listeningAnimationController.dispose();
    _voiceRecorder.dispose();
-    if (widget.chatBloc == null) {
-      _chatBloc.close();
-    }
    super.dispose();
  }

@@ -159,7 +170,11 @@ class _HomeScreenState extends State<HomeScreen>
          final hasItemCountChanged =
              state.items.length != _lastObservedItemCount;
          final waitingStateChanged = isWaitingNow != _lastObservedWaiting;
-          if (hasItemCountChanged || waitingStateChanged) {
+          final shouldAutoScroll =
+              !_isHistoryPaginationInFlight &&
+              !state.isLoadingHistory &&
+              (hasItemCountChanged || waitingStateChanged);
+          if (shouldAutoScroll) {
            _scheduleAutoScroll(animated: hasItemCountChanged);
          }
          _lastObservedItemCount = state.items.length;
@@ -373,7 +388,7 @@ class _HomeScreenState extends State<HomeScreen>
      return;
    }
    final chatBloc = context.read<ChatBloc>();
-    if (chatBloc.state.isLoadingHistory) {
+    if (chatBloc.state.isLoadingHistory || _isHistoryPaginationInFlight) {
      return;
    }
    final hasEarlierHistory = chatBloc.state.hasEarlierHistory;
@@ -383,7 +398,7 @@ class _HomeScreenState extends State<HomeScreen>
    final startedAt = DateTime.now();
    try {
      if (hasEarlierHistory) {
-        await chatBloc.loadMoreHistory();
+        await _loadMoreHistoryPreservingViewport(chatBloc);
      } else {
        Toast.show(context, '没有更早的历史记录了', type: ToastType.info);
      }
@@ -401,8 +416,63 @@ class _HomeScreenState extends State<HomeScreen>
    }
  }

-  void _onLoadMore(BuildContext context) {
-    context.read<ChatBloc>().loadMoreHistory();
+  Future<void> _onLoadMore(BuildContext context) async {
+    final chatBloc = context.read<ChatBloc>();
+    await _loadMoreHistoryPreservingViewport(chatBloc);
+  }
+
+  Future<void> _loadMoreHistoryPreservingViewport(ChatBloc chatBloc) async {
+    if (_isHistoryPaginationInFlight) {
+      return;
+    }
+    _captureHistoryViewportAnchor();
+    if (mounted) {
+      setState(() {
+        _isHistoryPaginationInFlight = true;
+      });
+    }
+    try {
+      await chatBloc.loadMoreHistory();
+    } finally {
+      _restoreHistoryViewportAnchor();
+      if (mounted) {
+        setState(() {
+          _isHistoryPaginationInFlight = false;
+        });
+      }
+    }
+  }
+
+  void _captureHistoryViewportAnchor() {
+    if (!_scrollController.hasClients) {
+      _historyViewportPixels = null;
+      _historyViewportMaxExtent = null;
+      return;
+    }
+    final position = _scrollController.position;
+    _historyViewportPixels = position.pixels;
+    _historyViewportMaxExtent = position.maxScrollExtent;
+  }
+
+  void _restoreHistoryViewportAnchor() {
+    final previousPixels = _historyViewportPixels;
+    final previousMaxExtent = _historyViewportMaxExtent;
+    _historyViewportPixels = null;
+    _historyViewportMaxExtent = null;
+    if (previousPixels == null || previousMaxExtent == null) {
+      return;
+    }
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      if (!_scrollController.hasClients) {
+        return;
+      }
+      final position = _scrollController.position;
+      final extentDelta = position.maxScrollExtent - previousMaxExtent;
+      final targetOffset = (previousPixels + extentDelta)
+          .clamp(position.minScrollExtent, position.maxScrollExtent)
+          .toDouble();
+      _scrollController.jumpTo(targetOffset);
+    });
  }

  bool _isAgentWaiting(ChatState state) {
@@ -742,8 +812,7 @@ class _HomeScreenState extends State<HomeScreen>
  }

  Widget _buildInputContainer(BuildContext context, ChatState state) {
-    final isWaitingAgent =
-        state.isWaitingFirstToken || state.isStreaming || state.isCancelling;
+    final isWaitingAgent = _isSendingMessage || _isAgentWaiting(state);
    return ValueListenableBuilder<TextEditingValue>(
      valueListenable: _messageController,
      builder: (context, value, child) {
@@ -797,6 +866,7 @@ class _HomeScreenState extends State<HomeScreen>
        alignment: Alignment.centerLeft,
        child: TextField(
          controller: _messageController,
+          focusNode: _messageFocusNode,
          minLines: 1,
          maxLines: 1,
          style: const TextStyle(
@@ -822,19 +892,38 @@ class _HomeScreenState extends State<HomeScreen>
            contentPadding: EdgeInsets.zero,
            filled: false,
          ),
+          onTap: _onTextFieldTap,
          onSubmitted: (_) => _sendMessage(context),
        ),
      ),
    );
  }

-  void _onRightActionTap(BuildContext context, ChatState state) {
-    if (_isTranscribing || _isRecording || _isSendingMessage) {
+  void _onTextFieldTap() {
+    final alreadyFocused = _messageFocusNode.hasFocus;
+    if (!alreadyFocused) {
+      _messageFocusNode.requestFocus();
      return;
    }
-    final isWaitingAgent =
-        state.isWaitingFirstToken || state.isStreaming || state.isCancelling;
-    if (isWaitingAgent) {
+    if (!_supportsProgrammaticKeyboardShow()) {
+      return;
+    }
+    SystemChannels.textInput.invokeMethod<void>('TextInput.show');
+  }
+
+  bool _supportsProgrammaticKeyboardShow() {
+    if (kIsWeb) {
+      return false;
+    }
+    return defaultTargetPlatform == TargetPlatform.android ||
+        defaultTargetPlatform == TargetPlatform.iOS;
+  }
+
+  void _onRightActionTap(BuildContext context, ChatState state) {
+    if (_isTranscribing || _isRecording) {
+      return;
+    }
+    if (_isSendingMessage || _isAgentWaiting(state)) {
      _onStopGenerating();
      return;
    }
@@ -849,9 +938,13 @@ class _HomeScreenState extends State<HomeScreen>
    if (_isRecording || _isTranscribing) {
      return;
    }
+    final willSwitchToText = _isHoldToSpeakMode;
    setState(() {
-      _isHoldToSpeakMode = !_isHoldToSpeakMode;
+      _isHoldToSpeakMode = !willSwitchToText;
    });
+    if (!willSwitchToText) {
+      _messageFocusNode.unfocus();
+    }
  }

  void _onHoldToSpeakStart() {
@@ -863,6 +956,14 @@ class _HomeScreenState extends State<HomeScreen>
  }

  void _onHoldToSpeakEnd() {
+    if (_isRecordingStarting) {
+      _shouldCancelWhenStartCompletes = false;
+      _shouldStopWhenStartCompletes = true;
+      return;
+    }
+    if (!_isRecording) {
+      return;
+    }
    if (_isCancelGestureActive) {
      HapticFeedback.selectionClick();
      _cancelRecording(showToast: false);
@@ -883,6 +984,11 @@ class _HomeScreenState extends State<HomeScreen>
  }

  void _onHoldToSpeakCancel() {
+    if (_isRecordingStarting) {
+      _shouldStopWhenStartCompletes = false;
+      _shouldCancelWhenStartCompletes = true;
+      return;
+    }
    _cancelRecording(showToast: false);
  }

@@ -1064,13 +1170,41 @@ class _HomeScreenState extends State<HomeScreen>
  }

  Future<void> _startRecording() async {
+    if (_isRecording || _isRecordingStarting) {
+      return;
+    }
+    if (mounted) {
+      setState(() {
+        _isRecordingStarting = true;
+        _shouldCancelWhenStartCompletes = false;
+        _shouldStopWhenStartCompletes = false;
+      });
+    }
    try {
      await _voiceRecorder.start();
      _listeningAnimationController.repeat();
      if (!mounted) {
        return;
      }
+      if (_shouldStopWhenStartCompletes || _shouldCancelWhenStartCompletes) {
+        final shouldCancelAfterStart =
+            _shouldCancelWhenStartCompletes || _isCancelGestureActive;
+        setState(() {
+          _isRecordingStarting = false;
+          _shouldCancelWhenStartCompletes = false;
+          _shouldStopWhenStartCompletes = false;
+          _isRecording = true;
+          _isCancelGestureActive = false;
+        });
+        if (shouldCancelAfterStart) {
+          await _cancelRecording(showToast: false);
+          return;
+        }
+        await _stopRecording(autoSendAfterTranscribe: true);
+        return;
+      }
      setState(() {
+        _isRecordingStarting = false;
        _isRecording = true;
        _isCancelGestureActive = false;
      });
@@ -1078,6 +1212,11 @@ class _HomeScreenState extends State<HomeScreen>
      if (!mounted) {
        return;
      }
+      setState(() {
+        _isRecordingStarting = false;
+        _shouldCancelWhenStartCompletes = false;
+        _shouldStopWhenStartCompletes = false;
+      });
      Toast.show(context, _readableError(error), type: ToastType.error);
    }
  }
@@ -1107,15 +1246,14 @@ class _HomeScreenState extends State<HomeScreen>
        Toast.show(context, '未识别到有效语音，请靠近麦克风并连续说话后重试', type: ToastType.error);
        return;
      }
-      _messageController.text = transcript;
+      _messageController.text = normalizedTranscript;
      _messageController.selection = TextSelection.fromPosition(
-        TextPosition(offset: transcript.length),
+        TextPosition(offset: normalizedTranscript.length),
      );
      if (autoSendAfterTranscribe) {
-        _messageController.text = normalizedTranscript;
-        _messageController.selection = TextSelection.fromPosition(
-          TextPosition(offset: normalizedTranscript.length),
-        );
+        setState(() {
+          _isTranscribing = false;
+        });
        await _sendMessage(context);
      }
    } catch (error) {
@@ -13,6 +13,7 @@ import 'features/auth/presentation/bloc/auth_bloc.dart';
 import 'features/auth/presentation/bloc/auth_event.dart';
 import 'features/auth/presentation/bloc/auth_state.dart';
 import 'features/calendar/data/services/calendar_service.dart';
+import 'features/chat/presentation/bloc/chat_bloc.dart';

 void main() async {
  WidgetsFlutterBinding.ensureInitialized();
@@ -45,8 +46,11 @@ class LinksyApp extends StatelessWidget {

  @override
  Widget build(BuildContext context) {
-    return BlocProvider<AuthBloc>.value(
-      value: authBloc,
+    return MultiBlocProvider(
+      providers: [
+        BlocProvider<AuthBloc>.value(value: authBloc),
+        BlocProvider<ChatBloc>(create: (_) => ChatBloc(apiClient: sl())),
+      ],
      child: BlocListener<AuthBloc, AuthState>(
        listenWhen: (previous, current) => previous != current,
        listener: (context, state) {