yixiong/flutter-template
Template
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: 初始化脚手架 — sunny_mochi 企业级 Flutter 模板

Browse Source 
Core 基础设施：Flavor 三包体系、Drift+SQLCipher 加密数据库
7 拦截器 Dio 网络栈、CrashReporter 崩溃日志、Sealed Failure 错误体系
5 色板主题系统、Auth 认证骨架（Clean Architecture）、Dev Panel、Mock Adapter

通过验证：flutter analyze（0 errors）、flutter test（全绿）、staging APK 74.8MB
This commit is contained in:
SkyJourney
2026-05-14 12:51:05 +08:00
commit 61017f1c39
204 changed files with 15386 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
lib/core/crash/crash_datasource.dart
+35
View File
@@ -0,0 +1,35 @@
import 'package:dio/dio.dart';
import 'package:sunny_mochi/core/config/api_paths.dart';
import 'package:sunny_mochi/core/crash/pending_crash_report.dart';
import 'package:sunny_mochi/core/network/api_response.dart';
import 'package:sunny_mochi/core/network/dio_client.dart';
import 'package:riverpod_annotation/riverpod_annotation.dart';
part 'crash_datasource.g.dart';
@riverpod
CrashDatasource crashDatasource(Ref ref) =>
CrashDatasource(ref.watch(dioClientProvider));
/// 崩溃报告上报接口。
///
/// **后端接口规范（待后端实现）**：
/// ```
/// POST /sys/crash-report
/// Headers: satoken: <token>（可选，未登录也应接受）
/// Body: { "kind", "error", "stackTrace", "occurredAt", "deviceModel", ... }
/// Response: { "retCode": "00000", "retMsg": "ok", "retData": null }
/// ```
// TODO(backend): 实现 POST /sys/crash-report 接口（接收客户端崩溃日志）
class CrashDatasource {
const CrashDatasource(this._dio);
final Dio _dio;
Future<void> sendCrashReport(PendingCrashReport report) async {
final resp = await _dio.post<Map<String, dynamic>>(
ApiPaths.crashReport,
data: report.toJson(),
);
parseEnvelope(resp.data, (j) => j).unwrapVoid();
}
}
lib/core/crash/crash_datasource.g.dart
+52
View File
@@ -0,0 +1,52 @@
// GENERATED CODE - DO NOT MODIFY BY HAND
part of 'crash_datasource.dart';
// **************************************************************************
// RiverpodGenerator
// **************************************************************************
// GENERATED CODE - DO NOT MODIFY BY HAND
// ignore_for_file: type=lint, type=warning
@ProviderFor(crashDatasource)
final crashDatasourceProvider = CrashDatasourceProvider._();
final class CrashDatasourceProvider
extends
$FunctionalProvider<CrashDatasource, CrashDatasource, CrashDatasource>
with $Provider<CrashDatasource> {
CrashDatasourceProvider._()
: super(
from: null,
argument: null,
retry: null,
name: r'crashDatasourceProvider',
isAutoDispose: true,
dependencies: null,
$allTransitiveDependencies: null,
);
@override
String debugGetCreateSourceHash() => _$crashDatasourceHash();
@$internal
@override
$ProviderElement<CrashDatasource> $createElement($ProviderPointer pointer) =>
$ProviderElement(pointer);
@override
CrashDatasource create(Ref ref) {
return crashDatasource(ref);
}
/// {@macro riverpod.override_with_value}
Override overrideWithValue(CrashDatasource value) {
return $ProviderOverride(
origin: this,
providerOverride: $SyncValueProvider<CrashDatasource>(value),
);
}
}
String _$crashDatasourceHash() => r'4506810eb85819b314f44127ee944feb65b56b20';
lib/core/crash/crash_dialog.dart
+206
View File
@@ -0,0 +1,206 @@
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:flutter_screenutil/flutter_screenutil.dart';
import 'package:sunny_mochi/core/crash/crash_datasource.dart';
import 'package:sunny_mochi/core/crash/pending_crash_report.dart';
import 'package:sunny_mochi/core/extensions/context_x.dart';
import 'package:sunny_mochi/core/widgets/app_toast.dart';
/// 崩溃报告对话框 — 下次启动时强制展示。
///
/// 用户体验：
/// - "发送报告"：POST 上报 → 关闭弹窗，后台继续正常启动
/// - "跳过"：直接关闭弹窗，继续正常启动
class CrashDialog extends ConsumerStatefulWidget {
const CrashDialog({super.key, required this.report});
final PendingCrashReport report;
@override
ConsumerState<CrashDialog> createState() => _CrashDialogState();
}
class _CrashDialogState extends ConsumerState<CrashDialog> {
bool _sending = false;
bool _showDetail = false;
Future<void> _send() async {
setState(() => _sending = true);
try {
await ref
.read(crashDatasourceProvider)
.sendCrashReport(widget.report);
if (mounted) {
Navigator.of(context).pop();
context.showToast('崩溃报告已发送，感谢您的反馈', type: ToastType.success);
}
} catch (e, st) {
if (mounted) {
setState(() => _sending = false);
context.showError(ref, e, st);
}
}
}
@override
Widget build(BuildContext context) {
final report = widget.report;
final time = report.occurredAtLocal;
final timeStr = time == null
? '未知时间'
: '${time.year}-${time.month.toString().padLeft(2, '0')}-'
'${time.day.toString().padLeft(2, '0')} '
'${time.hour.toString().padLeft(2, '0')}:'
'${time.minute.toString().padLeft(2, '0')}';
return AlertDialog(
shape: RoundedRectangleBorder(
borderRadius: BorderRadius.circular(16.r),
),
title: Row(
children: [
Icon(
Icons.warning_amber_rounded,
color: const Color(0xFFFF9F0A),
size: 22.sp,
),
SizedBox(width: 8.w),
Text(
'上次发生了意外退出',
style: TextStyle(fontSize: 16.sp, fontWeight: FontWeight.w600),
),
],
),
content: Column(
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(
'应用在 $timeStr 崩溃退出。发送崩溃报告有助于我们修复问题，报告不包含您的个人数据。',
style: TextStyle(
fontSize: 14.sp,
color: const Color(0xFF636366),
height: 1.5,
),
),
SizedBox(height: 12.h),
_InfoRow('设备', '${report.deviceModel} / ${report.osVersion}'),
_InfoRow('版本', '${report.appVersion}+${report.appBuild}'),
SizedBox(height: 8.h),
GestureDetector(
onTap: () => setState(() => _showDetail = !_showDetail),
child: Row(
children: [
Text(
'错误详情',
style: TextStyle(
fontSize: 13.sp,
color: Theme.of(context).colorScheme.primary,
fontWeight: FontWeight.w500,
),
),
Icon(
_showDetail
? Icons.expand_less_rounded
: Icons.expand_more_rounded,
size: 18.sp,
color: Theme.of(context).colorScheme.primary,
),
],
),
),
if (_showDetail) ...[
SizedBox(height: 8.h),
Container(
constraints: BoxConstraints(maxHeight: 160.h),
decoration: BoxDecoration(
color: const Color(0xFFF2F2F7),
borderRadius: BorderRadius.circular(8.r),
),
child: SingleChildScrollView(
padding:
EdgeInsets.symmetric(horizontal: 10.w, vertical: 8.h),
child: Text(
'${report.error}\n\n${_shortStack(report.stackTrace)}',
style: TextStyle(
fontSize: 11.sp,
color: const Color(0xFF3A3A3C),
fontFamily: 'monospace',
height: 1.4,
),
),
),
),
],
],
),
actions: [
TextButton(
onPressed: _sending ? null : () => Navigator.of(context).pop(),
child: Text(
'跳过',
style: TextStyle(
color: const Color(0xFF8E8E93),
fontSize: 15.sp,
),
),
),
FilledButton(
onPressed: _sending ? null : _send,
child: _sending
? SizedBox(
width: 16.w,
height: 16.w,
child: const CircularProgressIndicator.adaptive(
strokeWidth: 2,
valueColor: AlwaysStoppedAnimation(Colors.white),
),
)
: Text('发送报告', style: TextStyle(fontSize: 15.sp)),
),
],
);
}
String _shortStack(String stack) {
final lines = stack.split('\n');
if (lines.length <= 20) return stack;
return '${lines.take(20).join('\n')}\n...(${lines.length - 20} more lines)';
}
}
class _InfoRow extends StatelessWidget {
const _InfoRow(this.label, this.value);
final String label;
final String value;
@override
Widget build(BuildContext context) {
return Padding(
padding: EdgeInsets.only(bottom: 4.h),
child: Row(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
SizedBox(
width: 36.w,
child: Text(
label,
style: TextStyle(
fontSize: 12.sp,
color: const Color(0xFFAEAEB2),
),
),
),
Expanded(
child: Text(
value,
style: TextStyle(
fontSize: 12.sp,
color: const Color(0xFF636366),
),
),
),
],
),
);
}
}
lib/core/crash/crash_gate.dart
+42
View File
@@ -0,0 +1,42 @@
import 'dart:async';
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:sunny_mochi/core/crash/crash_dialog.dart';
import 'package:sunny_mochi/core/crash/crash_reporter.dart';
/// 应用根部崩溃检测门（wraps AppRoot）。
///
/// 在第一帧渲染完成后检查 [pendingCrashProvider]，若非 null 则强制弹出
/// [CrashDialog]（barrierDismissible: false）。
class CrashGate extends ConsumerStatefulWidget {
const CrashGate({super.key, required this.child});
final Widget child;
@override
ConsumerState<CrashGate> createState() => _CrashGateState();
}
class _CrashGateState extends ConsumerState<CrashGate> {
@override
void initState() {
super.initState();
final report = ref.read(pendingCrashProvider);
if (report != null) {
WidgetsBinding.instance.addPostFrameCallback((_) {
if (mounted) {
unawaited(
showDialog<void>(
context: context,
barrierDismissible: false,
builder: (_) => CrashDialog(report: report),
),
);
}
});
}
}
@override
Widget build(BuildContext context) => widget.child;
}
lib/core/crash/crash_reporter.dart
+129
View File
@@ -0,0 +1,129 @@
import 'dart:io';
import 'package:device_info_plus/device_info_plus.dart';
import 'package:flutter/foundation.dart';
import 'package:package_info_plus/package_info_plus.dart';
import 'package:path/path.dart' as p;
import 'package:path_provider/path_provider.dart';
import 'package:sunny_mochi/core/crash/pending_crash_report.dart';
import 'package:riverpod_annotation/riverpod_annotation.dart';
part 'crash_reporter.g.dart';
/// Riverpod provider：崩溃报告在 main.dart 通过 overrideWithValue 注入。
/// 默认值为 null（正常启动时无崩溃）。
@Riverpod(keepAlive: true)
PendingCrashReport? pendingCrash(Ref ref) => null;
/// 全局崩溃日志服务（纯静态，不依赖 Riverpod / Flutter framework）。
///
/// **生命周期**：
/// 1. `preInit()` — main() 最早期调用，异步缓存路径 + 设备信息
/// 2. `consumePending()` — 读取并删除上次崩溃文件（一次性消费）
/// 3. `installHooks()` — 在 SentrySetup.init appRunner 内调用，链式挂载钩子
///
/// **崩溃写入**：仅用 `File.writeAsStringSync(flush: true)`，绝对不能 await。
abstract class CrashReporter {
static String? _crashFilePath;
static String _deviceModel = 'unknown';
static String _osVersion = 'unknown';
static String _appVersion = 'unknown';
static String _appBuild = '0';
/// 步骤 1：异步预初始化（收集路径 + 设备信息）。
static Future<void> preInit() async {
try {
final dir = await getApplicationDocumentsDirectory();
_crashFilePath = p.join(dir.path, 'crash_report.json');
final pkg = await PackageInfo.fromPlatform();
_appVersion = pkg.version;
_appBuild = pkg.buildNumber;
if (kIsWeb) return;
if (Platform.isAndroid) {
final info = await DeviceInfoPlugin().androidInfo;
_deviceModel = '${info.manufacturer} ${info.model}'.trim();
_osVersion = 'Android ${info.version.release}';
} else if (Platform.isIOS) {
final info = await DeviceInfoPlugin().iosInfo;
_deviceModel = info.utsname.machine;
_osVersion = '${info.systemName} ${info.systemVersion}';
} else {
_deviceModel = Platform.operatingSystem;
_osVersion = Platform.operatingSystemVersion;
}
} catch (_) {
// preInit 失败不能阻断启动流程
}
}
/// 步骤 2：一次性消费崩溃文件（读取 + 立即删除）。
/// 返回 null 表示本次是正常启动。
static PendingCrashReport? consumePending() {
final path = _crashFilePath;
if (path == null) return null;
final file = File(path);
if (!file.existsSync()) return null;
try {
final raw = file.readAsStringSync();
file.deleteSync();
return PendingCrashReport.fromRawJson(raw);
} catch (_) {
try {
file.deleteSync();
} catch (_) {}
return null;
}
}
/// 步骤 3：安装全局崩溃钩子（必须在 SentrySetup appRunner 内调用）。
///
/// 采用链式挂载：先读出 Sentry 已设置的 handler，我们包一层写回，
/// 确保 Sentry 依然能接到所有错误。
static void installHooks() {
final previousOnError = PlatformDispatcher.instance.onError;
PlatformDispatcher.instance.onError = (error, stack) {
_writeCrashSync(kind: 'dart', error: error, stackTrace: stack);
return previousOnError?.call(error, stack) ?? false;
};
}
/// 同步写入崩溃文件（crash hook 专用，不能有任何 await）。
static void _writeCrashSync({
required String kind,
required Object error,
required StackTrace stackTrace,
}) {
final path = _crashFilePath;
if (path == null) return;
try {
final stackStr = stackTrace.toString();
final truncated = stackStr.length > 4096
? '${stackStr.substring(0, 4096)}\n...(truncated)'
: stackStr;
final report = PendingCrashReport(
kind: kind,
error: error.toString(),
stackTrace: truncated,
occurredAt: DateTime.now().toUtc().toIso8601String(),
deviceModel: _deviceModel,
osVersion: _osVersion,
appVersion: _appVersion,
appBuild: _appBuild,
);
File(path).writeAsStringSync(
report.toRawJson(),
flush: true,
);
} catch (_) {
// crash hook 内绝对不能抛出异常
}
}
}
lib/core/crash/crash_reporter.g.dart
+64
View File
@@ -0,0 +1,64 @@
// GENERATED CODE - DO NOT MODIFY BY HAND
part of 'crash_reporter.dart';
// **************************************************************************
// RiverpodGenerator
// **************************************************************************
// GENERATED CODE - DO NOT MODIFY BY HAND
// ignore_for_file: type=lint, type=warning
/// Riverpod provider：崩溃报告在 main.dart 通过 overrideWithValue 注入。
/// 默认值为 null（正常启动时无崩溃）。
@ProviderFor(pendingCrash)
final pendingCrashProvider = PendingCrashProvider._();
/// Riverpod provider：崩溃报告在 main.dart 通过 overrideWithValue 注入。
/// 默认值为 null（正常启动时无崩溃）。
final class PendingCrashProvider
extends
$FunctionalProvider<
PendingCrashReport?,
PendingCrashReport?,
PendingCrashReport?
>
with $Provider<PendingCrashReport?> {
/// Riverpod provider：崩溃报告在 main.dart 通过 overrideWithValue 注入。
/// 默认值为 null（正常启动时无崩溃）。
PendingCrashProvider._()
: super(
from: null,
argument: null,
retry: null,
name: r'pendingCrashProvider',
isAutoDispose: false,
dependencies: null,
$allTransitiveDependencies: null,
);
@override
String debugGetCreateSourceHash() => _$pendingCrashHash();
@$internal
@override
$ProviderElement<PendingCrashReport?> $createElement(
$ProviderPointer pointer,
) => $ProviderElement(pointer);
@override
PendingCrashReport? create(Ref ref) {
return pendingCrash(ref);
}
/// {@macro riverpod.override_with_value}
Override overrideWithValue(PendingCrashReport? value) {
return $ProviderOverride(
origin: this,
providerOverride: $SyncValueProvider<PendingCrashReport?>(value),
);
}
}
String _$pendingCrashHash() => r'4ccef6df51aa7ed093a0ac08518772bbd70ecc4e';
lib/core/crash/pending_crash_report.dart
+77
View File
@@ -0,0 +1,77 @@
import 'dart:convert';
/// 上次启动前崩溃的快照（从 crash_report.json 反序列化）。
///
/// 手写 fromJson/toJson — 文件写入发生在崩溃现场，不能依赖 code generator。
class PendingCrashReport {
const PendingCrashReport({
required this.kind,
required this.error,
required this.stackTrace,
required this.occurredAt,
required this.deviceModel,
required this.osVersion,
required this.appVersion,
required this.appBuild,
this.context,
});
/// 崩溃来源：dart（未捕获异常）/ zone（Zone 逃逸）
final String kind;
/// 原始异常 toString（技术细节，不展示给用户）
final String error;
/// 堆栈（已截断至 4096 字符）
final String stackTrace;
/// UTC ISO 8601
final String occurredAt;
final String deviceModel;
final String osVersion;
final String appVersion;
final String appBuild;
/// FlutterErrorDetails.context（仅 flutter 类型有值）
final String? context;
factory PendingCrashReport.fromJson(Map<String, dynamic> json) =>
PendingCrashReport(
kind: json['kind'] as String? ?? 'unknown',
error: json['error'] as String? ?? '',
stackTrace: json['stackTrace'] as String? ?? '',
occurredAt: json['occurredAt'] as String? ?? '',
deviceModel: json['deviceModel'] as String? ?? 'unknown',
osVersion: json['osVersion'] as String? ?? 'unknown',
appVersion: json['appVersion'] as String? ?? 'unknown',
appBuild: json['appBuild'] as String? ?? '0',
context: json['context'] as String?,
);
factory PendingCrashReport.fromRawJson(String raw) =>
PendingCrashReport.fromJson(jsonDecode(raw) as Map<String, dynamic>);
Map<String, dynamic> toJson() => {
'kind': kind,
'error': error,
'stackTrace': stackTrace,
'occurredAt': occurredAt,
'deviceModel': deviceModel,
'osVersion': osVersion,
'appVersion': appVersion,
'appBuild': appBuild,
if (context != null) 'context': context,
};
String toRawJson() => jsonEncode(toJson());
/// 崩溃时间（本地时区，用于 UI 展示）。
DateTime? get occurredAtLocal {
try {
return DateTime.parse(occurredAt).toLocal();
} catch (_) {
return null;
}
}
}