# Mom's Kitchen 项目基础支撑库说明

## 项目架构

```
lib/
├── main.dart                          # 应用入口
├── src/
│   ├── config/                        # 配置文件
│   │   ├── api_config.dart           # API 配置
│   │   └── app_config.dart           # 应用配置
│   ├── l10n/                          # 国际化
│   │   ├── app_en.arb                # 英文翻译
│   │   ├── app_zh.arb                # 中文翻译
│   │   ├── app_zh_Hant.arb           # 繁体中文翻译
│   │   ├── app_localizations.dart    # 生成的本地化代码
│   │   ├── app_localizations_en.dart # 英文实现
│   │   ├── app_localizations_zh.dart # 中文实现
│   │   └── app_localizations_zh_hant.dart # 繁体中文实现
│   ├── models/                        # 数据模型
│   │   └── theme_model.dart          # 主题模型
│   ├── pages/                         # 页面
│   │   ├── cart_page.dart            # 购物车页面
│   │   ├── example_page.dart         # 示例页面
│   │   ├── home_page.dart            # 首页
│   │   └── theme_demo_page.dart      # 主题设置页面
│   ├── services/                      # 服务层
│   │   ├── api_service.dart          # 网络请求服务
│   │   ├── app_info_service.dart     # 应用信息服务
│   │   ├── app_service.dart          # 应用服务（统一管理）
│   │   ├── animation_service.dart    # 动画管理服务
│   │   ├── logger_service.dart       # 日志管理服务
│   │   ├── notification_service.dart # 通知服务
│   │   ├── orientation_service.dart  # 屏幕方向服务
│   │   ├── permission_service.dart   # 权限管理服务
│   │   ├── screen_util_config.dart   # 屏幕适配配置
│   │   ├── storage_service.dart      # 本地存储服务
│   │   ├── theme_service.dart        # 主题管理服务
│   │   └── toast_service.dart        # 消息提示服务
│   ├── standards/                     # 页面规范
│   │   ├── app_pages.dart            # 页面注册表
│   │   ├── page_standards.dart       # 页面规范系统
│   │   └── page_validator.dart       # 页面验证系统
│   ├── utils/                         # 工具类
│   │   ├── app_logger.dart           # 全局日志工具
│   │   ├── common_utils.dart         # 通用工具
│   │   ├── date_utils.dart           # 日期工具
│   │   ├── network_utils.dart        # 网络工具
│   │   ├── platform_utils.dart       # 平台识别工具
│   │   └── string_utils.dart         # 字符串工具
│   └── widgets/                       # 通用组件
│       ├── adaptive_page_interface.dart # 自适应页面接口
│       ├── adaptive_scaffold.dart       # 自适应布局组件
│       ├── error_widget.dart           # 错误组件
│       ├── loading_indicator.dart      # 加载指示器
│       ├── product_card.dart           # 产品卡片
│       └── skeleton_loader.dart        # 骨架屏
```

## 已使用的依赖库

### 核心库

| 库名 | 版本 | 用途 | 使用位置 |
|------|------|------|----------|
| `cupertino_icons` | ^1.0.8 | iOS 风格图标 | 全局使用 |
| `flutter_localizations` | SDK | 国际化支持 | main.dart, app_localizations.dart |
| `intl` | ^0.20.2 | 国际化工具 | l10n 文件, date_utils.dart |
| `get` | git | 状态管理、路由管理、依赖注入 | ThemeService, AnimationService, main.dart 等 |

### 网络与存储

| 库名 | 版本 | 用途 | 使用位置 |
|------|------|------|----------|
| `dio` | ^5.9.2 | 网络请求 | ApiService |
| `dio_cache_interceptor` | ^3.5.0 | Dio 网络请求缓存 | ApiService |
| `shared_preferences` | git | 本地键值存储 | StorageService, ThemeService, AnimationService |
| `connectivity_plus` | git | 网络状态检测 | ApiService, NetworkUtils |
| `path_provider` | git | 文件路径获取 | LoggerService |

### 平台与工具

| 库名 | 版本 | 用途 | 使用位置 |
|------|------|------|----------|
| `flutter_local_notifications` | git | 本地通知 | NotificationService |
| `package_info_plus` | git | 应用信息 | AppInfoService |
| `fluttertoast` | git | Toast 消息提示 | ToastService |
| `share_plus` | git | 分享功能 | CommonUtils |
| `permission_handler` | git | 权限管理 | PermissionService |
| `device_info_plus` | git | 设备信息 | 待开发 |
| `logger` | ^2.7.0 | 日志管理 | LoggerService |
| `pretty_dio_logger` | ^1.4.0 | Dio 日志美化 | ApiService |

### UI 与动画

| 库名 | 版本 | 用途 | 使用位置 |
|------|------|------|----------|
| `flutter_adaptive_scaffold` | git | 自适应布局 | AdaptivePageInterface, AdaptiveScaffold |
| `animations` | git | 页面过渡动画 | AnimationService |
| `flutter_screenutil` | 本地 v5.9.3 | 屏幕适配 | 全局使用（支持鸿蒙） |

## 尚未使用的依赖库

| 库名 | 版本 | 用途 | 建议使用场景 |
|------|------|------|--------------|
| `pigeon` | git | Flutter 与原生平台通信 | 需要调用原生 API 时使用 |
| `orientation` | git | 屏幕方向控制 | 已改用 Flutter 原生 SystemChrome |
| `platform_info` | ^5.0.0 | 平台识别 | 已改用 dart:io 的 Platform |

## 建议添加的基础库

| 库名 | 用途 | 优先级 |
|------|------|--------|
| `image_picker` | 图片选择、拍照 | 高 |
| `url_launcher` | 打开 URL、拨打电话 | 高 |
| `path_provider` | 文件路径获取 | 中 |
| `camera` | 相机访问 | 中 |
| `geolocator` | 地理定位 | 中 |
| `fl_chart` | 图表库 | 低 |
| `sqflite` | SQLite 数据库 | 低 |

## 核心服务说明

### 1. ApiService（网络请求服务）

**功能：**
- 基于 Dio 封装的网络请求
- 支持缓存拦截器
- 网络状态检测
- 统一错误处理

**使用示例：**
```dart
final api = AppService.instance.api;
final response = await api.get('/products');
```

### 2. StorageService（本地存储服务）

**功能：**
- 基于 shared_preferences 封装
- 支持键值对存储
- 支持对象序列化

**使用示例：**
```dart
final storage = AppService.instance.storage;
await storage.setString('key', 'value');
final value = storage.getString('key');
```

### 3. ThemeService（主题管理服务）

**功能：**
- 动态切换白天/夜间模式
- 自定义主题色、次要色
- 字体大小调节
- 动画强度调节
- 状态栏沉浸设置
- 主题持久化存储

**使用示例：**
```dart
final theme = AppService.instance.theme;
await theme.toggleThemeMode();
await theme.setPrimaryColor(Colors.blue);
```

### 4. OrientationService（屏幕方向服务）

**功能：**
- 锁定屏幕方向
- 解锁屏幕方向
- 获取当前屏幕方向

**使用示例：**
```dart
final orientation = AppService.instance.orientation;
await orientation.lockPortrait();
await orientation.unlockOrientation();
```

### 5. NotificationService（通知服务）

**功能：**
- 本地通知管理
- 定时通知
- 进度通知
- 大文本通知
- 图片通知
- 通知权限请求

**使用示例：**
```dart
final notification = AppService.instance.notification;

// 请求权限
await notification.requestPermission();

// 显示普通通知
await notification.showNotification(
  id: 1,
  title: '标题',
  body: '内容',
);

// 显示定时通知
await notification.scheduleNotification(
  id: 2,
  title: '提醒',
  body: '该吃饭了！',
  scheduledDate: DateTime.now().add(Duration(hours: 1)),
);

// 取消通知
await notification.cancelNotification(1);
```

### 6. AppInfoService（应用信息服务）

**功能：**
- 获取应用名称
- 获取包名
- 获取版本号
- 获取构建号
- 版本比较
- 更新检测

**使用示例：**
```dart
final appInfo = AppService.instance.appInfo;

// 获取版本信息
print('版本: ${appInfo.version}');
print('构建号: ${appInfo.buildNumber}');
print('完整版本: ${appInfo.fullVersion}');

// 检查是否需要更新
if (appInfo.needsUpdate('2.0.0')) {
  print('需要更新应用');
}

// 获取应用信息摘要
print(appInfo.appInfoString);
```

### 7. ToastService（消息提示服务）

**功能：**
- 4 种消息类型：信息、成功（积极）、警告、错误（消极）
- 4 种显示样式：GetX、FlutterToast、默认、混合
- 样式动态切换
- 支持自定义显示时长

**消息类型：**
- `MessageType.info` - 普通信息（蓝色）
- `MessageType.success` - 成功/积极消息（绿色）
- `MessageType.warning` - 警告消息（橙色）
- `MessageType.error` - 错误/消极消息（红色）

**显示样式：**
- `ToastStyle.getx` - GetX 默认样式
- `ToastStyle.fluttertoast` - FlutterToast 样式
- `ToastStyle.default_` - 默认样式（Cupertino 风格）
- `ToastStyle.hybrid` - 混合样式（推荐）

**使用示例：**
```dart
final toast = AppService.instance.toast;

// 设置显示样式
toast.setStyle(ToastStyle.hybrid);

// 显示信息消息
await toast.info('这是一条信息');

// 显示成功消息（积极）
await toast.success('操作成功！');

// 显示警告消息
await toast.warning('请注意！');

// 显示错误消息（消极）
await toast.error('操作失败！');

// 自定义显示
await toast.show(
  '自定义消息',
  type: MessageType.info,
  style: ToastStyle.getx,
  duration: Duration(seconds: 3),
);

// 取消所有消息
toast.cancelAll();
```

### 8. PermissionService（权限管理服务）

**功能：**
- 支持 15 种常见权限类型（相机、麦克风、相册、位置等）
- 跨平台权限适配（iOS、Android、HarmonyOS、Web、Windows、macOS、Linux）
- 权限状态记录和查询功能
- 批量权限检查和请求功能

**使用示例：**
```dart
final permission = AppService.instance.permission;

// 检查单个权限
final status = await permission.checkPermission(PermissionType.camera);
if (status.isGranted) {
  // 权限已授予
}

// 请求单个权限
final result = await permission.requestPermission(PermissionType.camera);
if (result.isGranted) {
  // 权限已授予
}

// 批量检查权限
final permissions = [
  PermissionType.camera,
  PermissionType.microphone,
  PermissionType.photos,
];
final statuses = await permission.checkPermissions(permissions);

// 批量请求权限
final results = await permission.requestPermissions(permissions);

// 获取所有权限状态
final allStatuses = permission.getAllPermissionStatuses();
```

### 9. AnimationService（动画管理服务）

**功能：**
- 使用 `animations` 库实现专业动画效果
- 支持动画开关、速度、强度、曲线四种参数调节
- 提供 7 种预设模式（Standard、Fast、Slow、Smooth、Bouncy、Minimal、None）
- 支持 9 种动画曲线类型
- 配置持久化存储，应用重启后保持设置

**预设模式：**
- `AnimationPreset.standard` - 标准动画（默认）
- `AnimationPreset.fast` - 快速动画
- `AnimationPreset.slow` - 慢速动画
- `AnimationPreset.smooth` - 平滑动画
- `AnimationPreset.bouncy` - 弹性动画
- `AnimationPreset.minimal` - 最小动画
- `AnimationPreset.none` - 无动画

**使用示例：**
```dart
final animation = AppService.instance.animation;

// 获取动画配置
print('动画已启用: ${animation.enabled}');
print('动画速度: ${animation.speed}');
print('动画强度: ${animation.intensity}');
print('动画曲线: ${animation.curveType}');

// 设置动画参数
await animation.setEnabled(true);
await animation.setSpeed(1.5);
await animation.setIntensity(1.2);
await animation.setCurveType(AnimationCurveType.easeInOut);
await animation.setPreset(AnimationPreset.smooth);

// 使用动画组件
AnimatedButton(
  onPressed: () => print('点击'),
  child: Text('动画按钮'),
);

AnimatedCard(
  onTap: () => print('点击卡片'),
  child: Text('动画卡片'),
);

// 页面转场动画
PageTransitions.fadeThrough(
  child: NewPage(),
);
```

### 10. LoggerService（日志管理服务）

**功能：**
- 支持日志开关、级别、文件写入配置
- 支持 5 种日志级别（Debug、Info、Warning、Error、Off）
- 支持控制台输出和文件输出
- 支持日志文件自动清理（按大小和数量）
- 配置持久化存储

**使用示例：**
```dart
// 使用 AppLogger 全局工具类
AppLogger.d('调试信息');
AppLogger.i('普通信息');
AppLogger.w('警告信息');
AppLogger.e('错误信息');

// 或使用 LoggerService
final logger = AppService.instance.logger;
logger.debug('调试信息');
logger.info('普通信息');
logger.warning('警告信息');
logger.error('错误信息');

// 配置日志
await AppLogger.setEnabled(true);
await AppLogger.setWriteToFile(true);

// 获取日志文件
final files = await AppLogger.getLogFiles();
final content = await AppLogger.getLogContent();

// 清空日志
await AppLogger.clearLogs();
```

### 11. ScreenUtilConfig（屏幕适配配置）

**功能：**
- 设计稿尺寸配置（默认 375x812）
- 最小字体适配开关
- 分屏模式开关
- 缩放开关控制
- 配置持久化存储

**使用示例：**
```dart
// 初始化
final screenUtil = AppService.instance.screenUtil;
screenUtil.initScreenUtil(context);

// 或异步初始化
await screenUtil.ensureScreenSizeAndInit(context);

// 配置设计稿尺寸
await screenUtil.setDesignSize(Size(375, 812));
await screenUtil.setDesignWidth(375);
await screenUtil.setDesignHeight(812);

// 配置适配选项
await screenUtil.setMinTextAdapt(true);
await screenUtil.setSplitScreenMode(true);
await screenUtil.setScaleEnabled(true);

// 使用扩展方法
Container(
  width: 100.w,      // 按设计稿比例缩放
  height: 50.h,
  padding: EdgeInsets.all(16.w),
  child: Text(
    'Hello',
    style: TextStyle(fontSize: 14.sp),  // 字体缩放
  ),
)

// 禁用缩放时，扩展方法返回原始值
await screenUtil.setScaleEnabled(false);
// 此时 100.w 返回 100.0
```

## 页面规范系统

> 📖 详细文档请查看 [PAGE_STANDARDS.md](./PAGE_STANDARDS.md)

页面规范系统提供统一的页面构建标准，确保所有页面遵循统一的开发规范。

### 核心组件

| 组件 | 说明 |
|------|------|
| `PageStandards` | 页面规范配置类 |
| `PageStandardsMixin` | 页面混入，自动注入规范 |
| `StandardPage` | 标准页面基类 |
| `PageValidator` | 页面验证器 |
| `PageRegistry` | 页面注册表 |

### 快速使用

```dart
class MyPage extends StandardPage {
  const MyPage({super.key});
  
  @override
  State<MyPage> createState() => _MyPageState();
}

class _MyPageState extends StandardPageState<MyPage> {
  @override
  Widget buildPage(BuildContext context) {
    return CupertinoPageScaffold(
      backgroundColor: backgroundColor,  // 自动获取主题背景色
      child: Text(
        l10n.appTitle,  // 自动获取多语言
        style: textStyle,  // 自动获取主题文字样式
      ),
    );
  }
}
```

---

## 主题系统说明

> 📖 页面主题使用详见 [PAGE_STANDARDS.md](./PAGE_STANDARDS.md#页面规范系统)

### 主题属性

创建新页面时，**必须读取所有主题值**：

```dart
@override
Widget build(BuildContext context) {
  final theme = AppService.instance.theme;
  
  final isDarkMode = theme.isDarkMode;
  final primaryColor = theme.primaryColor;
  final secondaryColor = theme.secondaryColor;
  final fontSize = theme.fontSize;
  final textColor = theme.textColor;
  final backgroundColor = theme.backgroundColor;
  
  return CupertinoPageScaffold(
    backgroundColor: backgroundColor,
    child: Text('Hello', style: TextStyle(color: textColor)),
  );
}
```

### 主题属性说明

| 属性 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `isDarkMode` | bool | 是否为深色模式 | false |
| `primaryColor` | Color | 主题色 | Colors.blue |
| `secondaryColor` | Color | 次要色 | Colors.orange |
| `fontSize` | double | 基础字体大小 | 16.0 |
| `textColor` | Color | 文字颜色 | Colors.black |
| `backgroundColor` | Color | 背景颜色 | Colors.white |

---

## 国际化说明

### 支持的语言

- 英文（en）
- 中文（zh）
- 繁体中文（zh_Hant）

### 使用方法

```dart
final l10n = AppLocalizations.of(context)!;
Text(l10n.appTitle)
```

### 添加新的翻译

1. 编辑 `lib/src/l10n/app_en.arb` 和 `lib/src/l10n/app_zh.arb`
2. 运行 `flutter gen-l10n` 生成代码

## 注意事项

### 1. 组件风格

- **优先使用 iOS 风格组件**（Cupertino）
- 若 iOS 无对应组件，再使用 Material 组件
- 示例：使用 `CupertinoButton` 而非 `ElevatedButton`

### 2. 响应式布局

- 使用 `LayoutBuilder` 和 `MediaQuery` 实现响应式
- 支持横竖屏切换
- 适配不同屏幕尺寸

### 3. 骨架屏与动画

- 页面加载时显示骨架屏
- 使用 `AnimationService` 统一管理动画
- 动画参数可在设置中调节（开关、速度、强度、曲线）
- 使用 `AnimatedButton`、`AnimatedCard` 等动画组件

### 4. 网络图片加载

- 使用 `Image.network` 加载网络图片
- 添加 `loadingBuilder` 和 `errorBuilder`
- 示例：
```dart
Image.network(
  url,
  loadingBuilder: (context, child, loadingProgress) {
    if (loadingProgress == null) return child;
    return const CupertinoActivityIndicator();
  },
  errorBuilder: (context, error, stackTrace) {
    return const Icon(CupertinoIcons.exclamationmark_circle);
  },
)
```

### 5. 平台识别

使用 `PlatformUtils` 识别平台：

```dart
final platform = PlatformUtils();
if (platform.isIOS) {
  // iOS 特定逻辑
} else if (platform.isAndroid) {
  // Android 特定逻辑
} else if (platform.isHarmonyOS) {
  // 鸿蒙特定逻辑
}
```

### 6. 状态管理

使用 GetX 进行状态管理：

```dart
// 定义响应式变量
final count = 0.obs;

// 更新值
count.value++;

// 监听变化
Obx(() => Text('${count.value}'))
```

### 7. 路由管理

使用 GetX 进行路由管理：

```dart
// 跳转到新页面
Get.to(const NewPage());

// 返回上一页
Get.back();

// 替换当前页面
Get.off(const NewPage());

// 清空栈并跳转
Get.offAll(const HomePage());
```

### 8. 依赖注入

使用 GetX 进行依赖注入：

```dart
// 注册服务
Get.put(ThemeService());

// 获取服务
final theme = Get.find<ThemeService>();
```

## 开发规范

### 1. 文件命名

- 文件名使用小写下划线：`theme_service.dart`
- 类名使用大驼峰：`ThemeService`

### 2. 导入顺序

```dart
// 1. Flutter SDK
import 'package:flutter/material.dart';
import 'package:flutter/cupertino.dart';

// 2. 第三方库
import 'package:get/get.dart';

// 3. 项目内部文件
import 'package:mom_kitchen/src/services/app_service.dart';
```

### 3. 注释规范

- 使用中文注释
- 公共方法必须添加注释说明
- 复杂逻辑添加行内注释

### 4. 代码风格

- 使用 `const` 构造函数
- 使用 `final` 定义不可变变量
- 避免使用 `dynamic`，明确类型

## 常见问题

### Q1: 如何添加新的主题属性？

1. 在 `ThemeService` 中添加新的响应式变量
2. 在 `_loadTheme()` 和 `_saveTheme()` 中添加加载和保存逻辑
3. 添加 getter 方法
4. 在 `getThemeData()` 中应用新属性
5. 更新本文档的主题属性表格

### Q2: 如何添加新的语言支持？

1. 在 `l10n.yaml` 中添加新的语言代码
2. 创建对应的 ARB 文件：`app_xx.arb`
3. 运行 `flutter gen-l10n` 生成代码

### Q3: 如何使用未使用的库？

参考本文档"尚未使用的依赖库"表格中的建议使用场景，在相应的服务或页面中集成。

### Q4: 如何创建新页面？

请参考 [PAGE_STANDARDS.md](./PAGE_STANDARDS.md#最佳实践) 中的最佳实践部分。

---

## 相关文档

| 文档 | 说明 |
|------|------|
| [PAGE_STANDARDS.md](./PAGE_STANDARDS.md) | 页面规范与验证系统详细说明 |
| [CHANGELOG.md](../../CHANGELOG.md) | 项目更新日志 |

---

**最后更新时间：** 2026-04-08
**维护者：** Mom's Kitchen 开发团队