@umacloud/knowledge 1.0.1

package/mobile/01-standards/flutter-complete.md

@@ -0,0 +1,384 @@
+---
+title: Flutter 完整开发标准
+category: mobile/standards
+version: 1.0.0
+last_updated: 2026-03-20
+maintainer: Excellent（11964948@qq.com）
+knowledge_score: 9.3/10
+domain: mobile
+difficulty: intermediate
+quality_score: 70
+---
+
+# 开发：Excellent（11964948@qq.com）
+
+## Flutter 完整开发标准
+
+### 1. 架构与分层
+- 遵循 Clean Architecture 或 MVVM 模式。
+- 表现层、领域层、数据层严格分离。
+- 依赖注入使用 get_it 或 Provider。
+- 路由管理使用 go_router 或 auto_route。
+
+### 2. 组件设计原则
+- Widget 单一职责，代码不超过 300 行。
+- 使用 const 构造函数优化性能。
+- 拆分 StatelessWidget 和 StatefulWidget。
+- 复用组件提取到独立文件。
+
+### 3. 状态管理策略
+- 简单状态：Provider + ChangeNotifier。
+- 复杂状态：Riverpod 或 Bloc。
+- 表单状态：FormKey + TextEditingController。
+- 避免过度使用全局状态。
+
+### 4. 性能优化策略
+- 使用 const Widget 减少重建。
+- ListView.builder 渲染长列表。
+- 图片使用 cached_network_image。
+- 避免在 build 方法中执行耗时操作。
+- 使用 Isolate 执行 CPU 密集型任务。
+
+### 5. 原生集成与插件
+- 使用 Platform Channel 与原生通信。
+- 复杂功能使用现有插件（相机、地图、支付）。
+- 处理好 Android/iOS 平台差异。
+- 权限申请使用 permission_handler。
+
+### 6. 网络与数据存储
+- 网络请求使用 dio + retrofit。
+- 本地存储使用 Hive 或 Drift。
+- 离线优先策略（Offline First）。
+- 网络状态监听和重试机制。
+
+### 7. 错误处理与监控
+- 全局错误捕获（FlutterError.onError）。
+- 网络错误统一处理。
+- 集成 Sentry 或 Firebase Crashlytics。
+- 关键路径埋点监控。
+
+### 8. 测试策略
+- 单元测试：业务逻辑、工具类。
+- Widget 测试：组件交互和渲染。
+- 集成测试：关键流程端到端。
+- 测试覆盖率 >= 70%。
+
+### 9. 安全规范
+- 敏感数据使用 flutter_secure_storage。
+- 禁止硬编码密钥，使用 .env 文件。
+- HTTPS 强制开启。
+- 代码混淆（--obfuscate）。
+
+### 10. 国际化与适配
+- 使用 intl 和 flutter_localizations。
+- 文案抽取为 ARB 文件。
+- 适配不同屏幕尺寸（MediaQuery）。
+- 支持 RTL 布局。
+
+## 代码示例
+
+### Widget 组件示例
+```dart
+// 开发：Excellent（11964948@qq.com）
+// 功能：用户头像组件
+// 作用：展示用户头像，支持默认头像和加载状态
+// 创建时间：2026-03-20
+// 最后修改：2026-03-20
+
+import 'package:flutter/material.dart';
+import 'package:cached_network_image/cached_network_image.dart';
+
+class UserAvatar extends StatelessWidget {
+  final String? imageUrl;
+  final double size;
+  final bool isLoading;
+
+  const UserAvatar({
+    Key? key,
+    this.imageUrl,
+    this.size = 48.0,
+    this.isLoading = false,
+  }) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    if (isLoading) {
+      return Container(
+        width: size,
+        height: size,
+        decoration: BoxDecoration(
+          color: Colors.grey[200],
+          shape: BoxShape.circle,
+        ),
+        child: Center(
+          child: SizedBox(
+            width: size * 0.5,
+            height: size * 0.5,
+            child: const CircularProgressIndicator(strokeWidth: 2),
+          ),
+        ),
+      );
+    }
+
+    return ClipOval(
+      child: CachedNetworkImage(
+        imageUrl: imageUrl ?? 'https://via.placeholder.com/150',
+        width: size,
+        height: size,
+        fit: BoxFit.cover,
+        placeholder: (context, url) => Container(
+          color: Colors.grey[200],
+          child: Icon(
+            Icons.person,
+            size: size * 0.6,
+            color: Colors.grey[400],
+          ),
+        ),
+        errorWidget: (context, url, error) => Container(
+          color: Colors.grey[200],
+          child: Icon(
+            Icons.error_outline,
+            size: size * 0.6,
+            color: Colors.red,
+          ),
+        ),
+      ),
+    );
+  }
+}
+```
+
+### 网络请求封装示例
+```dart
+// 开发：Excellent（11964948@qq.com）
+// 功能：API 客户端封装
+// 作用：统一管理网络请求，包含认证和错误处理
+// 创建时间：2026-03-20
+// 最后修改：2026-03-20
+
+import 'package:dio/dio.dart';
+import 'package:flutter_secure_storage/flutter_secure_storage.dart';
+
+class ApiClient {
+  static const String baseUrl = 'https://api.example.com';
+  final Dio _dio;
+  final FlutterSecureStorage _storage = const FlutterSecureStorage();
+
+  ApiClient() : _dio = Dio(BaseOptions(baseUrl: baseUrl)) {
+    _dio.interceptors.add(
+      InterceptorsWrapper(
+        onRequest: (options, handler) async {
+          final token = await _storage.read(key: 'auth_token');
+          if (token != null) {
+            options.headers['Authorization'] = 'Bearer $token';
+          }
+          return handler.next(options);
+        },
+        onError: (error, handler) {
+          if (error.response?.statusCode == 401) {
+            // 处理认证失败
+            _handleUnauthorized();
+          }
+          return handler.next(error);
+        },
+      ),
+    );
+  }
+
+  Future<T> get<T>(String endpoint) async {
+    try {
+      final response = await _dio.get<T>(endpoint);
+      return response.data as T;
+    } on DioException catch (e) {
+      throw _handleError(e);
+    }
+  }
+
+  Future<T> post<T>(String endpoint, dynamic data) async {
+    try {
+      final response = await _dio.post<T>(endpoint, data: data);
+      return response.data as T;
+    } on DioException catch (e) {
+      throw _handleError(e);
+    }
+  }
+
+  Exception _handleError(DioException error) {
+    switch (error.type) {
+      case DioExceptionType.connectionTimeout:
+      case DioExceptionType.sendTimeout:
+      case DioExceptionType.receiveTimeout:
+        return Exception('网络请求超时，请检查网络连接');
+      case DioExceptionType.badResponse:
+        final message = error.response?.data['message'] ?? '请求失败';
+        return Exception(message);
+      default:
+        return Exception('网络请求失败：${error.message}');
+    }
+  }
+
+  void _handleUnauthorized() {
+    // 清除本地存储的 token
+    _storage.delete(key: 'auth_token');
+    // 跳转到登录页面
+    // 需要通过全局导航器处理
+  }
+}
+
+final apiClient = ApiClient();
+```
+
+### 状态管理示例（Provider）
+```dart
+// 开发：Excellent（11964948@qq.com）
+// 功能：用户状态管理
+// 作用：管理用户登录状态和用户信息
+// 创建时间：2026-03-20
+// 最后修改：2026-03-20
+
+import 'package:flutter/material.dart';
+
+class User {
+  final String id;
+  final String name;
+  final String email;
+  final String? avatar;
+
+  User({
+    required this.id,
+    required this.name,
+    required this.email,
+    this.avatar,
+  });
+
+  factory User.fromJson(Map<String, dynamic> json) {
+    return User(
+      id: json['id'],
+      name: json['name'],
+      email: json['email'],
+      avatar: json['avatar'],
+    );
+  }
+}
+
+class UserProvider extends ChangeNotifier {
+  User? _user;
+  bool _isLoading = false;
+  String? _error;
+
+  User? get user => _user;
+  bool get isLoading => _isLoading;
+  String? get error => _error;
+  bool get isAuthenticated => _user != null;
+
+  Future<void> login(String email, String password) async {
+    _isLoading = true;
+    _error = null;
+    notifyListeners();
+
+    try {
+      // 模拟 API 调用
+      await Future.delayed(const Duration(seconds: 2));
+
+      _user = User(
+        id: '1',
+        name: 'John Doe',
+        email: email,
+        avatar: 'https://via.placeholder.com/150',
+      );
+
+      _isLoading = false;
+      notifyListeners();
+    } catch (e) {
+      _isLoading = false;
+      _error = e.toString();
+      notifyListeners();
+      rethrow;
+    }
+  }
+
+  Future<void> logout() async {
+    _user = null;
+    notifyListeners();
+  }
+
+  void clearError() {
+    _error = null;
+    notifyListeners();
+  }
+}
+
+// 使用示例
+class UserAvatarWidget extends StatelessWidget {
+  const UserAvatarWidget({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return Consumer<UserProvider>(
+      builder: (context, userProvider, child) {
+        if (userProvider.isLoading) {
+          return const CircularProgressIndicator();
+        }
+
+        if (!userProvider.isAuthenticated) {
+          return const Icon(Icons.person);
+        }
+
+        return UserAvatar(
+          imageUrl: userProvider.user?.avatar,
+          size: 48,
+        );
+      },
+    );
+  }
+}
+```
+
+## 反模式识别
+
+### 反模式列表
+- 在 build 方法中执行耗时操作或网络请求。
+- 过度使用 StatefulWidget 导致性能下降。
+- 未使用 const 构造函数导致不必要的重建。
+- ListView 未使用 builder 导致内存问题。
+- 状态管理混乱，全局状态滥用。
+- 未处理网络请求失败和超时。
+- 图片未缓存导致重复加载。
+- 未做权限检查直接调用原生功能。
+
+## 检查清单
+
+### 开发阶段
+- [ ] 架构分层清晰，职责明确
+- [ ] 使用 const Widget 优化性能
+- [ ] ListView 使用 builder 渲染长列表
+- [ ] 图片使用缓存策略
+- [ ] 状态管理合理，避免过度共享
+- [ ] 网络请求封装统一，包含错误处理
+- [ ] 敏感数据存储使用安全存储方案
+- [ ] 权限申请流程完整
+- [ ] 关键路径添加埋点监控
+- [ ] 国际化文案抽取完成
+
+### 测试阶段
+- [ ] 单元测试覆盖率 >= 70%
+- [ ] Widget 测试覆盖关键组件
+- [ ] 集成测试覆盖关键流程
+- [ ] 不同设备尺寸适配测试
+- [ ] 网络异常场景测试
+- [ ] 性能指标符合基线
+
+### 发布阶段
+- [ ] 生产环境配置正确
+- [ ] 代码混淆和加固完成
+- [ ] 崩溃监控集成完成
+- [ ] 版本号和构建号更新
+- [ ] 应用商店素材准备完成
+- [ ] 更新日志编写完成
+
+## 参考资料
+- Flutter 官方文档：https://flutter.dev/docs
+- Dart 官方文档：https://dart.dev/guides
+- Provider 文档：https://pub.dev/packages/provider
+- Riverpod 文档：https://riverpod.dev/
+- Dio 文档：https://pub.dev/packages/dio

package/mobile/01-standards/ios-design-hig.md

@@ -0,0 +1,78 @@
+---
+id: ios-design-hig
+title: iOS 设计规范（Apple Human Interface Guidelines · 官方）
+domain: mobile
+category: 01-standards
+difficulty: intermediate
+tags: [ios, 设计规范, hig, human-interface-guidelines, apple, sf字体, dynamic-type, 导航, tabbar, 安全区, 深色模式, sf-symbols, 商业级]
+quality_score: 95
+last_updated: 2026-06-19
+---
+
+# iOS 设计规范（Apple Human Interface Guidelines · 官方）
+
+> 纯 Claude/Codex 写 iOS UI 常常"web 味"很重、不像原生。本标准是 Apple 官方 HIG 的落地要点——做出**像 iOS 原生**的界面。设计 iOS 应用前必读。
+
+## 1. 四大核心原则（HIG）
+
+- **Clarity 清晰**：内容优先，文字清晰可读，图标精准，留白充分。
+- **Deference 谦让**：UI 让位于内容，不喧宾夺主；用半透明/模糊衬托而非抢戏。
+- **Depth 层次**：用真实的层级与过渡传达结构（卡片、模态滑入、层叠）。
+- **Consistency 一致**：用系统标准组件与交互，符合用户跨 Apple 生态的既有习惯。
+
+## 2. 排版（Typography）
+
+- 用系统字体 **San Francisco (SF Pro)**：正文 SF Pro Text（≤19pt），大标题 SF Pro Display（≥20pt）；中文用苹方(PingFang SC)。
+- **必须支持 Dynamic Type**（用户可调字号，无障碍）——用文本样式(Large Title/Title/Body/Caption…)而非写死字号，布局随字号弹性。
+- 建立清晰的字阶层级（Large Title → Title → Headline → Body → Footnote）。
+
+## 3. 颜色与材质
+
+- 用**语义系统颜色**（`label`/`secondaryLabel`/`systemBackground`/`systemBlue`…）而非硬编码，自动适配深浅色。
+- 一个克制的品牌强调色 + 系统色；不要满屏高饱和。
+- 善用材质(Materials/毛玻璃)做层次；遵循系统的浅色/深色双模式。
+
+## 4. 布局与适配
+
+- 内容尊重**安全区(Safe Area)**：避开刘海/灵动岛/Home Indicator/状态栏。
+- 标准边距与对齐；触控目标 **≥44×44pt**。
+- 适配各机型尺寸、横竖屏、iPad(分屏/多窗)；用 Auto Layout/SwiftUI 自适应，不写死像素。
+- 尊重 reduce motion / increase contrast 等无障碍设置。
+
+## 5. 导航范式（iOS 特有，别套 web）
+
+- **Tab Bar**：底部，切换 App 顶层模块，iPhone 上**最多 5 个**。
+- **Navigation Bar**：层级钻取(drill-down)，左上返回，标题居中/大标题。
+- **Modal Sheet**：聚焦单一任务（新建/编辑），可下拉关闭；破坏性确认用 Action Sheet/Alert。
+- 手势：边缘左滑返回、列表左滑操作、下拉刷新——符合系统习惯。
+
+## 6. 组件（用系统标准件）
+
+- 优先用系统组件（按钮、列表 List、表单、分段控件、开关、Picker、搜索栏、上下文菜单），自带正确外观/交互/无障碍。
+- 图标用 **SF Symbols**（与系统一致、随字重/字号缩放、支持多色），**不要用 emoji 当功能图标**。
+- 列表用 inset grouped 等系统样式；空态/加载态/错误态都要做。
+
+## 7. 体验细节
+
+- 即时反馈：点击态、加载指示、触感反馈(Haptics)。
+- 流畅自然的转场动画（遵循系统时长/曲线），不要花哨突兀。
+- 首次启动/权限请求有上下文说明；尊重用户选择。
+
+## 8. 反模式（出现即不合格 / "不像 iOS"）
+
+- 把 web/安卓的 UI 范式硬搬到 iOS（如安卓 FAB、底部抽屉当主导航乱用）。
+- 写死字号不支持 Dynamic Type；硬编码颜色不适配深色。
+- 忽略安全区导致内容被刘海/Home 条遮挡；触控目标过小。
+- 用 emoji 当图标而非 SF Symbols；自绘一堆非标准控件却没做无障碍。
+- Tab 超过 5 个；模态/导航滥用，不符系统手势。
+
+## 9. 最低交付 checklist
+
+- [ ] 遵循 Clarity/Deference/Depth/Consistency；用系统标准组件。
+- [ ] SF/苹方字体 + Dynamic Type + 清晰字阶；语义系统颜色 + 深色适配。
+- [ ] 安全区适配 + ≥44pt 触控 + 多机型/横竖屏/iPad 自适应。
+- [ ] 导航用 Tab(≤5)/Nav Bar/Modal + 系统手势；SF Symbols 图标无 emoji。
+- [ ] 反馈/Haptics/自然转场 + 三态 + 无障碍(VoiceOver/对比度/reduce motion)。
+
+---
+**参考（官方）**：Apple Human Interface Guidelines (developer.apple.com/design/human-interface-guidelines)、SF Symbols、Dynamic Type、Safe Area、SwiftUI。

package/mobile/01-standards/mobile-app-standard.md

@@ -0,0 +1,85 @@
+---
+id: mobile-app-standard
+title: 移动 App 开发标准（iOS/Android/跨平台 · 商业级）
+domain: mobile
+category: 01-standards
+difficulty: intermediate
+tags: [移动, mobile, ios, android, swiftui, jetpack compose, flutter, react-native, mvvm, 导航, 离线, 推送, hig, material, 商业级]
+quality_score: 95
+last_updated: 2026-06-19
+---
+
+# 移动 App 开发标准（iOS/Android/跨平台 · 商业级）
+
+> 移动 App 不是"把网页塞进手机"。要遵循平台设计规范、处理生命周期/离线/弱网、做好性能与发布。本标准覆盖原生(SwiftUI/Compose)与跨平台(Flutter/RN)。
+
+## 1. 架构（客户端也要分层）
+
+- 用 **MVVM / MVI** 等单向数据流架构：View(声明式 UI) ↔ ViewModel/State(状态+逻辑) ↔ Repository(数据访问) ↔ 领域/网络/本地存储。
+- UI 与业务逻辑分离；ViewModel 不持有 UI 引用、可测试。
+- 数据访问统一 Repository：网络(API)、本地(DB/缓存)在此封装，UI 不直接调网络。
+- 依赖注入装配；按 feature 模块组织。
+- 声明式 UI（SwiftUI / Jetpack Compose / Flutter / RN）优先，注意避免不必要重组/重建。
+
+## 2. 平台设计规范（UI/交互按平台，别用 web 范式）
+
+- **iOS**：遵循 **Human Interface Guidelines (HIG)**——原生导航(NavigationStack)、SF Symbols 图标、原生手势、安全区(notch/灵动岛)、动效自然。
+- **Android**：遵循 **Material Design 3**——Material 组件、返回手势、自适应布局、动态取色(Material You)。
+- 尊重各平台导航范式（iOS 顶部返回 + tab；Android 系统返回）；不要把一端的导航硬搬另一端。
+- 适配多屏尺寸、刘海/挖孔、深色模式、字体缩放(动态字体/无障碍)、横竖屏。
+
+## 3. 生命周期与状态
+
+- 正确处理 App/页面生命周期（前后台切换、被系统回收恢复、配置变更如旋转）。
+- 状态保存与恢复：进程被杀后能恢复关键状态。
+- 后台限制：遵守平台后台执行规则，长任务用平台机制(WorkManager/BGTaskScheduler)。
+
+## 4. 网络、离线与弱网
+
+- 统一网络层 + 超时/重试；处理弱网/无网，给明确反馈而非卡死。
+- **离线优先**（适用场景）：本地缓存/数据库(SQLite/Room/CoreData/Realm)，离线可读，联网同步；冲突有解决策略。
+- 列表分页 + 下拉刷新 + 上拉加载；图片懒加载 + 缓存 + 占位。
+- 乐观更新提升体感，失败回滚。
+
+## 5. 性能
+
+- 列表用平台高效列表（LazyColumn/List/FlatList/ListView.builder）+ 回收复用，不一次渲染全部。
+- 图片：合适尺寸/格式、缓存、避免主线程解码大图。
+- 主线程不做重计算/IO（避免掉帧/ANR）；耗时放后台线程/协程/isolate。
+- 控制重组/重渲染（Compose 稳定性、SwiftUI 最小化 body、RN memo/FlatList 优化）。
+- 启动速度、包体积（按需加载、资源压缩、Android App Bundle）。
+
+## 6. 原生能力与权限
+
+- 权限**按需申请 + 说明用途**（相机/定位/通知/相册），尊重拒绝，提供降级。
+- 推送：iOS APNs / Android FCM / 鸿蒙 Push；处理 token、点击跳转、前后台展示。
+- 安全存储敏感数据用 Keychain(iOS)/Keystore+EncryptedSharedPrefs(Android)，**不用明文 SharedPreferences/UserDefaults 存 token**。
+- 深链接(Universal Links/App Links)、分享、支付(IAP/三方)按平台规范。
+
+## 7. 发布与合规
+
+- 商店审核：iOS App Store / Google Play / 华为应用市场各有规范（隐私清单、权限说明、内容合规）。
+- 版本/热更新：遵守平台政策（iOS 禁止下发可执行代码）；崩溃监控(Crashlytics/Sentry)。
+- 隐私合规：隐私政策、数据收集声明(App Privacy)、个保法/GDPR。
+
+## 8. 反模式（出现即不合格）
+
+- 用 web 的 UI/交互范式套移动端；忽略 HIG/Material。
+- UI 直接调网络、无 Repository/分层；ViewModel 持有 View。
+- 不处理生命周期/进程回收/弱网；列表一次渲染全部。
+- 主线程做重 IO/计算导致卡顿/ANR。
+- token 明文存 UserDefaults/SharedPreferences；权限一次性全要不说明。
+- 不做崩溃监控、不适配深色/多尺寸/动态字体。
+
+## 9. 最低交付 checklist
+
+- [ ] MVVM/MVI 分层 + Repository 数据访问 + 声明式 UI + feature 模块。
+- [ ] 遵循 iOS HIG / Android Material；导航按平台；适配多屏/深色/动态字体/安全区。
+- [ ] 正确生命周期 + 状态保存恢复 + 后台规则。
+- [ ] 统一网络层 + 弱网/离线处理 + 列表分页/缓存 + 乐观更新。
+- [ ] 列表复用 + 图片优化 + 主线程不阻塞 + 控制重组 + 包体优化。
+- [ ] 权限按需+说明、敏感数据安全存储、推送、深链、IAP 按规范。
+- [ ] 商店合规 + 崩溃监控 + 隐私声明。
+
+---
+**参考**：Apple HIG、Material Design 3、SwiftUI/Jetpack Compose、Flutter/React Native 最佳实践、离线优先、移动安全存储。