@ohos-cpf/3rdloop 0.0.11 → 0.0.13

package/vendor/Server/Skills/flutter-demo-code-generator/references/CODE_STANDARDS.md

@@ -0,0 +1,328 @@
+# Flutter Demo 代码规范速查
+
+本文档为 `flutter-demo-code-generator` 技能的代码生成提供规范速查，涵盖命名规则、Dart 最佳实践、日志规范、错误处理模式等。
+
+---
+
+## 一、文件命名规范
+
+### 目录命名
+
+格式：`{三位序号}_{snake_case功能描述}`
+
+| 规则 | 说明 | 示例 |
+|------|------|------|
+| 三位序号 | 用零补齐，保证目录排序与 Demo 序号一致 | `001`、`012`、`100` |
+| snake_case 描述 | 全小写字母，单词间用下划线，3-5 个单词 | `check_support_and_config` |
+| 完整目录名 | `{序号}_{描述}` | `001_check_support_and_config` |
+
+### Dart 文件命名
+
+格式：`{snake_case功能描述}_page.dart`
+
+| Demo 中文名 | 目录名 | 文件名 | 类名 |
+|-----------|-------|--------|------|
+| 环境检测与版本查询 Demo | `001_check_support` | `check_support_page.dart` | `CheckSupportPage` |
+| 控制器初始化与资源释放 Demo | `002_controller_lifecycle` | `controller_lifecycle_page.dart` | `ControllerLifecyclePage` |
+| 播放控制与进度管理 Demo | `003_playback_control` | `playback_control_page.dart` | `PlaybackControlPage` |
+| 音量控制 Demo | `004_volume_control` | `volume_control_page.dart` | `VolumeControlPage` |
+
+### 辅助文件命名（可选）
+
+若 Demo 需要独立的数据类或辅助 Widget：
+- 数据类：`{snake_case名}_model.dart`
+- 辅助 Widget：`{snake_case名}_widget.dart`
+
+---
+
+## 二、Dart/Flutter 编码规范
+
+### 2.1 类型声明
+
+```dart
+// ✅ 优先使用具体类型，避免 dynamic
+final String result = library.getVersion();
+final List<String> items = [];
+final Map<String, int> counts = {};
+
+// ✅ 泛型参数完整声明
+final StreamController<PlaybackEvent> _controller = StreamController<PlaybackEvent>();
+
+// ❌ 避免 dynamic（除非确实无法确定类型）
+dynamic result = library.something(); // 避免
+```
+
+### 2.2 Null Safety
+
+```dart
+// ✅ 可空类型声明
+SomeController? _controller;
+
+// ✅ 安全访问
+_controller?.dispose();
+
+// ✅ 空值合并
+final text = _resultText ?? '（暂无结果）';
+
+// ✅ 非空断言（仅在确定不为空的场景使用）
+_controller!.play(); // 仅在已验证 _controller != null 后使用
+```
+
+### 2.3 const 优化（强制要求）
+
+```dart
+// ✅ 不依赖运行时状态的 Widget 必须用 const
+const Text('固定标题'),
+const SizedBox(height: 16),
+const Divider(),
+const CircleAvatar(child: Text('01')),
+
+// ✅ 构造函数也应声明 const（当所有字段都是编译期常量时）
+class DemoButton extends StatelessWidget {
+  const DemoButton({super.key, required this.label, required this.onPressed});
+  // ...
+}
+
+// ❌ 有状态 Widget 不能用 const
+const Text(_resultText), // ❌ _resultText 是变量
+```
+
+### 2.4 setState 最佳实践
+
+```dart
+// ✅ 合并多个状态更新到一次 setState()
+setState(() {
+  _isLoading = false;
+  _resultText = '结果：$result';
+  _callbackCount++;
+});
+
+// ❌ 避免多次连续 setState()（每次都触发重建）
+setState(() => _isLoading = false);
+setState(() => _resultText = '结果：$result'); // 避免
+
+// ✅ 检查 mounted 后再调用 setState（异步回调中）
+void _onAsyncCallback(String result) {
+  if (!mounted) return; // 页面已销毁，不再更新
+  setState(() => _resultText = result);
+}
+```
+
+### 2.5 Widget 提取规范
+
+```dart
+// ✅ 将重复使用或复杂的 Widget 抽取为方法或独立类
+Widget _buildResultArea() {
+  if (_isLoading) {
+    return const Center(child: CircularProgressIndicator());
+  }
+  return Container(
+    padding: const EdgeInsets.all(12),
+    decoration: BoxDecoration(
+      color: Colors.grey[100],
+      borderRadius: BorderRadius.circular(8),
+    ),
+    child: SelectableText(_resultText.isEmpty ? '（暂无结果）' : _resultText),
+  );
+}
+```
+
+---
+
+## 三、日志规范
+
+### 3.1 Tag 命名
+
+```dart
+// ✅ 每个文件有独立的日志 Tag 常量
+const String _kTag = 'FlutterVideoPlayer_CheckSupportPage';
+
+// Tag 命名规则：{LibraryName}_{ComponentName}
+// - 不超过 40 字符
+// - 只含字母、数字、下划线
+// - LibraryName：包名去掉前缀下划线，使用 UpperCamelCase（如 FlutterVideoPlayer）
+// - ComponentName：页面组件名（如 CheckSupportPage）
+```
+
+### 3.2 日志函数使用
+
+```dart
+import 'dart:developer' as dev;
+
+// ✅ INFO 级别：重要操作成功、页面生命周期
+dev.log('Page appeared', name: _kTag);
+dev.log('_initController succeeded', name: _kTag);
+
+// ✅ DEBUG 级别：方法入口、中间步骤
+dev.log('_checkSupport called', name: _kTag);
+dev.log('Volume set to: $volume', name: _kTag);
+
+// ✅ ERROR 级别：捕获异常（必须传 error 和 stackTrace）
+dev.log('_initController failed', name: _kTag, error: e, stackTrace: stack);
+
+// ✅ 敏感信息不应以明文输出（例如用户 token、账号）
+// dev.log('Token: $token', name: _kTag); // ❌ 安全违规
+```
+
+### 3.3 必须添加日志的位置
+
+| 位置 | 说明 | 示例 |
+|------|------|------|
+| `initState()` | 页面出现 | `dev.log('Page appeared', name: _kTag)` |
+| `dispose()` | 页面销毁 | `dev.log('Page disposed', name: _kTag)` |
+| 每个操作方法入口 | 调用前记录 | `dev.log('_play called', name: _kTag)` |
+| 接口调用成功 | 记录关键返回值 | `dev.log('initialized, duration: $duration', name: _kTag)` |
+| 捕获到异常 | 传 error 和 stackTrace | `dev.log('failed', name: _kTag, error: e, stackTrace: stack)` |
+| 重要状态变化 | 监听回调中 | `dev.log('Playback state: $state', name: _kTag)` |
+
+---
+
+## 四、错误处理规范
+
+### 4.1 异步接口标准模式
+
+```dart
+/// 初始化控制器（异步模式标准模板）
+Future<void> _initController() async {
+  dev.log('_initController called', name: _kTag);
+  setState(() => _isLoading = true);
+  try {
+    await _controller.initialize();
+    dev.log('_initController succeeded', name: _kTag);
+    if (!mounted) return; // 页面可能已销毁，不再更新状态
+    setState(() {
+      _status = '已初始化';
+      _isLoading = false;
+    });
+  } catch (e, stack) {
+    dev.log('_initController failed', name: _kTag, error: e, stackTrace: stack);
+    if (!mounted) return;
+    setState(() {
+      _status = '初始化失败：$e';
+      _isLoading = false;
+    });
+  }
+}
+```
+
+### 4.2 同步接口标准模式
+
+```dart
+/// 检测设备支持（同步模式标准模板）
+void _checkSupport() {
+  dev.log('_checkSupport called', name: _kTag);
+  try {
+    final isSupported = LibraryUtils.isHardwareDecodingSupported();
+    dev.log('_checkSupport result: $isSupported', name: _kTag);
+    setState(() {
+      _supportText = isSupported ? '支持硬件解码 ✅' : '不支持硬件解码 ❌';
+    });
+  } catch (e, stack) {
+    dev.log('_checkSupport failed', name: _kTag, error: e, stackTrace: stack);
+    setState(() => _supportText = '检测失败：$e');
+  }
+}
+```
+
+### 4.3 Navigator 错误处理（不抛异常，不需要 try/catch）
+
+```dart
+// ✅ Navigator.push 用 await 捕获返回结果即可
+// Flutter Navigator 不抛出异常（除非路由配置错误）
+Navigator.push(
+  context,
+  MaterialPageRoute(builder: (_) => const SomePage()),
+);
+```
+
+---
+
+## 五、资源生命周期管理
+
+所有持有的资源必须在 `dispose()` 中释放：
+
+```dart
+// 声明（在 State 类中，非 @override 变量）
+SomeController? _controller;
+StreamSubscription<SomeEvent>? _subscription;
+Timer? _timer;
+
+@override
+void dispose() {
+  dev.log('Page disposed, releasing resources', name: _kTag);
+
+  // 释放三方库实例
+  _controller?.dispose();
+  _controller = null;
+
+  // 取消 Stream 订阅
+  _subscription?.cancel();
+  _subscription = null;
+
+  // 清除定时器
+  _timer?.cancel();
+  _timer = null;
+
+  super.dispose(); // 必须在最后调用
+}
+```
+
+---
+
+## 六、双计数器诊断模式
+
+对涉及回调/事件的异步链路，规划双计数器帮助诊断：
+
+```dart
+// 计数器状态变量（必须在 setState() 中更新）
+int _triggerCount = 0;     // 触发/调用次数
+int _callbackCount = 0;    // 回调实际被调用次数
+
+// 触发操作
+void _triggerAction() {
+  dev.log('_triggerAction called', name: _kTag);
+  setState(() => _triggerCount++);
+  library.doSomething();
+}
+
+// 回调处理
+void _onCallback(SomeEvent event) {
+  dev.log('Callback received: $event', name: _kTag);
+  if (!mounted) return;
+  setState(() {
+    _callbackCount++;
+    _lastEvent = event.toString();
+  });
+}
+
+// UI 展示（诊断区域）
+Widget _buildDiagnosticArea() {
+  return Column(
+    children: [
+      Text('触发次数: $_triggerCount'),
+      Text('回调次数: $_callbackCount'),
+      if (_triggerCount > 0 && _callbackCount == 0)
+        const Text('⚠️ 已触发但回调未收到，请检查监听注册', style: TextStyle(color: Colors.orange)),
+      if (_callbackCount > 0 && _triggerCount == _callbackCount)
+        const Text('✅ 链路正常', style: TextStyle(color: Colors.green)),
+    ],
+  );
+}
+```
+
+---
+
+## 七、常见 pubspec.yaml 依赖示例
+
+```yaml
+dependencies:
+  flutter:
+    sdk: flutter
+  # 三方库（根据实际情况填写）
+  flutter_video_player: ^1.0.0
+
+dev_dependencies:
+  flutter_test:
+    sdk: flutter
+  flutter_lints: ^3.0.0
+```

package/vendor/Server/Skills/flutter-demo-code-generator/references/DEMO_DOC_PARSING.md

@@ -0,0 +1,126 @@
+# Demo 描述文档解析规范
+
+> 本文档定义 `flutter-demo-code-generator` 技能的输入文档解析规则：字段映射、接口签名解析、中文→英文命名推导、步骤→UI 控件映射。
+
+---
+
+## 1. 文档定位
+
+| 属性 | 说明 |
+|------|------|
+| 文件名模式 | `*Flutter测试demo描述.md` |
+| 产出方 | 通常由 Demo 描述文档生成技能（上游）产出 |
+| 典型结构 | 库基本信息 → 测试 Demo 描述列表（表格）→ 接口覆盖矩阵 |
+
+---
+
+## 2. Demo 条目表字段映射
+
+| 文档字段 | 用途 |
+|----------|------|
+| 序号 | 目录序号（三位补零，如 `1` → `001`） |
+| 测试 Demo 名称（中文） | 导航卡片 `title`、页面 AppBar 标题 `[{序号}] {名称}` |
+| 测试 Demo 描述 | 导航卡片 `description`（≤40字）+ 页面说明卡片文案 |
+| 测试 Demo 步骤 | 页面操作区设计依据：**每一步映射为一个控件/按钮** |
+| 测试 Demo 预期结果 | 结果展示区文案与成功/失败判定提示 |
+| 对应函数接口 | 文件头 Dart doc 注释 + 页面内实际调用的接口清单 |
+
+---
+
+## 3. 接口签名解析规则
+
+描述文档中的接口签名格式及对应的生成模式：
+
+| 签名形式 | 示例 | 生成模式 |
+|----------|------|----------|
+| 顶层函数 | `getSDKVersion(): String` | 直接调用；无 `Future` → **同步模式** |
+| 顶层异步函数 | `loadConfig(): Future<Map>` | 直接调用 → **异步模式** |
+| 类方法 | `controller.play(): void` | 需先构造实例（本页 init 或独立初始化 Demo 提供） |
+| 类异步方法 | `controller.initialize(): Future<void>` | **异步模式** + mounted 检查 |
+| 构造函数 | `VideoPlayerController(config)` | 生成实例化调用，参数按签名构造 |
+| 事件流/监听 | `onPlaybackState.listen`、`addListener(callback)` | **监听器模式**（StreamSubscription + 双计数器） |
+
+**参数解析**：签名中的可选参数（`{autoPlay, initialVolume}`）生成默认值调用，并在行内注释说明可调参数。
+
+---
+
+## 4. 中文名 → 英文命名推导
+
+### 4.1 推导流程
+
+```
+中文名称 → 提取核心功能词 → 翻译为英文（3-5 个单词）
+  → snake_case  → 目录名 / 文件名
+  → UpperCamelCase + Page → 类名
+```
+
+### 4.2 推导示例
+
+| 中文名 | 功能词 | 目录名 | 文件名 | 类名 |
+|--------|--------|--------|--------|------|
+| 环境检测与版本查询 Demo | check support | `001_check_support` | `check_support_page.dart` | `CheckSupportPage` |
+| 控制器初始化与资源释放 Demo | controller lifecycle | `002_controller_lifecycle` | `controller_lifecycle_page.dart` | `ControllerLifecyclePage` |
+| 播放控制与进度管理 Demo | playback control | `003_playback_control` | `playback_control_page.dart` | `PlaybackControlPage` |
+| 音量控制 Demo | volume control | `004_volume_control` | `volume_control_page.dart` | `VolumeControlPage` |
+
+### 4.3 约束
+
+- 同一描述文档内目录名、类名**不得重复**
+- 仅使用小写字母、数字、下划线（目录/文件），不得含中文拼音混排
+- 序号必须三位数字（`001`、`010`、`100`），保证文件系统排序与 Demo 序号一致
+
+---
+
+## 5. 步骤 → UI 控件映射规则
+
+| 步骤动作词 | 生成控件 |
+|-----------|----------|
+| 点击 / 按下 / 触发 | `ElevatedButton` / `IconButton` |
+| 输入 / 设置 / 填写 URL | `TextField`（含 `TextEditingController`，dispose 中释放） |
+| 调节 / 滑动（音量/进度） | `Slider`（onChanged 中调用 set 接口） |
+| 开关 / 切换 | `Switch` / `Checkbox` |
+| 等待 / 加载 | `CircularProgressIndicator` + 状态文案（异步模式自动携带） |
+| 观察 / 查看 / 验证 | 结果展示区（`SelectableText`）或双计数器诊断区 |
+
+**步骤依赖处理**：当步骤存在先后依赖（如"先初始化，再播放"），用页面状态变量控制按钮可用性（初始化完成前播放按钮 `onPressed: null`）。
+
+---
+
+## 6. 文件规划表模板
+
+Phase 1.3 使用（内部工作记录，不写入输出）：
+
+```
+文件规划：
+┌──────────────────────────────────────────────────────────────────┐
+│ 主入口：lib/main.dart                                             │
+│ 主导航页：lib/pages/demo_home_page.dart                           │
+│                                                                  │
+│ Demo 页面列表（按序号）：                                          │
+│   lib/pages/001_check_support/                                   │
+│     check_support_page.dart   → Demo 1：环境检测（同步模式）        │
+│   lib/pages/002_controller_lifecycle/                            │
+│     controller_lifecycle_page.dart  → Demo 2：生命周期（异步模式）  │
+│   lib/pages/003_playback_control/                                │
+│     playback_control_page.dart      → Demo 3：播放控制（监听模式）  │
+│   ...                                                            │
+└──────────────────────────────────────────────────────────────────┘
+
+接口校验记录（Phase 2 产出）：
+  ✅ isHardwareDecodingSupported(): bool — 规格匹配
+  ✅ initialize(): Future<void> — 规格匹配
+  ⚠️ setSpeed(rate): void — 规格为 setSpeed(double speed)，以源码为准
+```
+
+---
+
+## 7. 边界情况处理
+
+| 边界情况 | 处理规则 |
+|----------|----------|
+| 同一接口出现在多个 Demo | 各页面独立调用，允许重复（Demo 之间互不依赖） |
+| Demo 无对应接口（纯 UI 演示） | 生成静态展示页面，文件头注明"本 Demo 无接口调用" |
+| 接口含可选参数 | 生成默认参数调用 + 行内注释说明 |
+| 步骤依赖前序步骤 | 页面内状态机控制按钮可用性（见第 5 节） |
+| 接口返回复杂对象（Map/List） | 结果区用 `JsonEncoder.withIndent('  ')` 格式化后 `SelectableText` 展示 |
+| 描述文档表格缺列（如无预期结果） | 对应字段以"以实际运行为准"占位，不阻塞生成 |