create-dwy 0.5.0 → 0.6.0

package/templates/claude-global/rules/dwy-flutter-network.md

@@ -0,0 +1,222 @@
+---
+description: Flutter Dio 网络层 + 拦截器 + 错误处理
+paths:
+  - "**/core/network/**/*.dart"
+  - "**/dio_client.dart"
+  - "**/interceptors/**/*.dart"
+  - "**/network/**/*.dart"
+---
+
+# Flutter 网络层规范
+
+## 一、网络层（Dio）
+
+### 1.1 Dio 实例封装
+
+```dart
+// core/network/dio_client.dart
+import 'package:dio/dio.dart';
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+part 'dio_client.g.dart';
+
+@Riverpod(keepAlive: true)
+Dio dio(Ref ref) {
+  final env = ref.watch(envProvider);
+  final dio = Dio(BaseOptions(
+    baseUrl: env.apiBaseUrl,
+    connectTimeout: const Duration(seconds: 10),
+    receiveTimeout: const Duration(seconds: 30),
+    headers: {'Content-Type': 'application/json'},
+  ));
+
+  dio.interceptors.addAll([
+    TokenInterceptor(ref),
+    RefreshInterceptor(ref),
+    UnwrapInterceptor(),
+    ErrorInterceptor(ref),
+  ]);
+
+  return dio;
+}
+```
+
+### 1.2 拦截器
+
+**Token 注入：**
+```dart
+class TokenInterceptor extends Interceptor {
+  final Ref ref;
+  TokenInterceptor(this.ref);
+
+  @override
+  void onRequest(RequestOptions options, RequestInterceptorHandler handler) async {
+    final token = await TokenStorage.getAccessToken();
+    if (token != null) {
+      options.headers['Authorization'] = 'Bearer $token';
+    }
+    handler.next(options);
+  }
+}
+```
+
+**响应解包（对齐 eapi 格式）：**
+```dart
+class UnwrapInterceptor extends Interceptor {
+  @override
+  void onResponse(Response response, ResponseInterceptorHandler handler) {
+    final data = response.data;
+    if (data is Map && data.containsKey('code') && data.containsKey('data')) {
+      // eapi 格式: {code: "SUCCESS", message: "success", data: {...}, timestamp: ...}
+      response.data = data['data'];
+    }
+    handler.next(response);
+  }
+}
+```
+
+**401 Token 刷新（使用 QueuedInterceptor 防止竞态）：**
+
+> **关键：** 使用 `QueuedInterceptor` 而非 `Interceptor`。QueuedInterceptor 串行处理请求，
+> 刷新期间后续 401 请求自动排队等待，无需手动管理队列。
+> 刷新 token 必须用**独立 Dio 实例**，避免被自身拦截器死锁。
+
+```dart
+class RefreshInterceptor extends QueuedInterceptor {
+  final Ref ref;
+  final Dio _refreshDio = Dio();  // 独立实例，不经过拦截器链
+
+  RefreshInterceptor(this.ref);
+
+  @override
+  void onError(DioException err, ErrorInterceptorHandler handler) async {
+    if (err.response?.statusCode != 401) {
+      return handler.next(err);
+    }
+
+    try {
+      final refreshToken = await TokenStorage.getRefreshToken();
+      if (refreshToken == null) {
+        ref.read(authProvider.notifier).logout();
+        return handler.next(err);
+      }
+
+      // 用独立 Dio 实例刷新 token
+      final response = await _refreshDio.post(
+        '${ref.read(envProvider).apiBaseUrl}/api/auth/refresh',
+        data: {'refresh_token': refreshToken},
+      );
+
+      final newToken = response.data['data']['access_token'];
+      await TokenStorage.saveAccessToken(newToken);
+
+      // 用新 token 重试原请求
+      err.requestOptions.headers['Authorization'] = 'Bearer $newToken';
+      final retryResponse = await ref.read(dioProvider).fetch(err.requestOptions);
+      handler.resolve(retryResponse);
+    } catch (e) {
+      // 刷新失败 → 登出
+      ref.read(authProvider.notifier).logout();
+      handler.next(err);
+    }
+  }
+}
+```
+
+### 1.3 Repository 模式
+
+```dart
+// features/user/data/user_repository.dart
+class UserRepository {
+  final Dio _dio;
+  UserRepository(this._dio);
+
+  Future<List<User>> getUsers({int page = 1, int pageSize = 20}) async {
+    final response = await _dio.get('/api/users', queryParameters: {
+      'page': page,
+      'page_size': pageSize,
+    });
+    final data = response.data as Map<String, dynamic>;
+    return (data['items'] as List).map((e) => User.fromJson(e)).toList();
+  }
+
+  Future<User> getUser(int id) async {
+    final response = await _dio.get('/api/users/$id');
+    return User.fromJson(response.data);
+  }
+
+  Future<void> deleteUser(int id) async {
+    await _dio.delete('/api/users/$id');
+  }
+}
+
+// Provider 注入 Repository
+@riverpod
+UserRepository userRepository(Ref ref) {
+  return UserRepository(ref.watch(dioProvider));
+}
+```
+
+### 1.4 禁止事项
+
+- 禁止 `http.get()` / `HttpClient` / 裸 `Dio()` 不加拦截器
+- 禁止在 Widget 中直接调用 Dio（通过 Provider + Repository）
+- 禁止硬编码 API 地址（走环境配置）
+
+---
+
+## 二、错误处理（Flutter）
+
+Dio interceptor 统一处理，模式与前端对齐：
+
+```dart
+class ErrorInterceptor extends Interceptor {
+  @override
+  void onError(DioException err, ErrorInterceptorHandler handler) {
+    switch (err.response?.statusCode) {
+      case 401: // → 跳转登录
+      case 403: // → 提示无权限
+      case 422: // → 提取 message 显示
+    }
+    handler.next(err);
+  }
+}
+```
+
+---
+
+## 三、网络层规范（跨端对齐）
+
+### 3.1 Flutter 唯一方式
+
+**唯一方式：** Dio + 拦截器，封装与 ekit request 对齐。
+
+```dart
+// core/network/dio_client.dart
+class DioClient {
+  late final Dio _dio;
+
+  DioClient({required String baseUrl}) {
+    _dio = Dio(BaseOptions(baseUrl: baseUrl))
+      ..interceptors.addAll([
+        TokenInterceptor(),    // 注入 Authorization header
+        RefreshInterceptor(),  // 401 自动刷新
+        UnwrapInterceptor(),   // 解包 {code, data, message} → data
+        ErrorInterceptor(),    // 统一错误处理
+      ]);
+  }
+}
+```
+
+**禁止：** `http.get()`、`HttpClient`、裸 `Dio()` 不加拦截器
+
+### 3.2 响应解包
+
+前端和 Flutter 的解包逻辑必须与后端 eapi response 格式对齐：
+
+```
+后端返回: { code: "SUCCESS", message: "success", data: {...}, timestamp: ... }
+                                                      ↓ unwrap
+前端/Flutter 拿到: {...}  (直接是 data 的内容)
+```
+
+分页响应解包后拿到 `{ items, total, page, page_size }`（保持 snake_case 对齐后端 JSON）。

package/templates/claude-global/rules/dwy-flutter-router.md

@@ -0,0 +1,97 @@
+---
+description: Flutter GoRouter 路由规范
+paths:
+  - "**/app.dart"
+  - "**/router/**/*.dart"
+  - "**/routes/**/*.dart"
+---
+
+# Flutter 路由规范
+
+## 一、路由（GoRouter）
+
+### 1.1 路由定义
+
+```dart
+// app.dart 或 shared/providers/router_provider.dart
+@riverpod
+GoRouter router(Ref ref) {
+  final auth = ref.watch(authProvider);
+
+  return GoRouter(
+    initialLocation: '/',
+    redirect: (context, state) {
+      final isLoggedIn = auth.isAuthenticated;
+      final isLoginRoute = state.matchedLocation == '/login';
+
+      if (!isLoggedIn && !isLoginRoute) return '/login';
+      if (isLoggedIn && isLoginRoute) return '/';
+      return null;
+    },
+    routes: [
+      GoRoute(
+        path: '/login',
+        builder: (context, state) => const LoginPage(),
+      ),
+      ShellRoute(
+        builder: (context, state, child) => AppShell(child: child),
+        routes: [
+          GoRoute(
+            path: '/',
+            builder: (context, state) => const HomePage(),
+          ),
+          GoRoute(
+            path: '/users',
+            builder: (context, state) => const UserListPage(),
+          ),
+          GoRoute(
+            path: '/users/:id',
+            builder: (context, state) {
+              final id = int.parse(state.pathParameters['id']!);
+              return UserDetailPage(userId: id);
+            },
+          ),
+        ],
+      ),
+    ],
+  );
+}
+```
+
+### 1.2 导航
+
+```dart
+// 声明式导航
+context.go('/users');            // 替换当前页面栈
+context.push('/users/123');      // 压入新页面
+context.pop();                   // 返回
+
+// 禁止使用 Navigator.push / Navigator.pushNamed
+```
+
+### 1.3 底部导航（StatefulShellRoute）
+
+```dart
+StatefulShellRoute.indexedStack(
+  builder: (context, state, navigationShell) {
+    return ScaffoldWithBottomNav(navigationShell: navigationShell);
+  },
+  branches: [
+    StatefulShellBranch(routes: [
+      GoRoute(path: '/home', builder: (_, __) => const HomePage()),
+    ]),
+    StatefulShellBranch(routes: [
+      GoRoute(path: '/profile', builder: (_, __) => const ProfilePage()),
+    ]),
+  ],
+)
+```
+
+### 1.4 路由规则
+
+| 规则 | 说明 |
+|------|------|
+| 全部用 GoRouter | 禁止 `Navigator.push` / `Navigator.pushNamed` |
+| 认证守卫在 redirect 中 | 不在每个页面单独检查 |
+| 路径参数用 `:id` | `/users/:id`，通过 `state.pathParameters['id']` 获取 |
+| 查询参数用 `state.uri.queryParameters` | 分页、筛选等 |

package/templates/claude-global/rules/dwy-flutter-testing.md

@@ -0,0 +1,94 @@
+---
+description: Flutter / Dart 测试规范(mocktail + ProviderContainer + Widget 测试)
+paths:
+  - "**/test/**/*.dart"
+  - "**/*_test.dart"
+---
+
+# Flutter 测试规范
+
+## 一、测试分类
+
+| 类型 | 位置 | 工具 | 重点 |
+|------|------|------|------|
+| Unit Test | `test/features/{name}/` | flutter_test + mocktail | Repository、Service、工具函数 |
+| Provider Test | `test/features/{name}/` | flutter_test + ProviderContainer | Provider 状态变化 |
+| Widget Test | `test/features/{name}/` | flutter_test + ProviderScope.overrides | 页面渲染和交互 |
+
+## 二、Provider 测试
+
+```dart
+import 'package:flutter_test/flutter_test.dart';
+import 'package:mocktail/mocktail.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+class MockUserRepository extends Mock implements UserRepository {}
+
+void main() {
+  late MockUserRepository mockRepo;
+  late ProviderContainer container;
+
+  setUp(() {
+    mockRepo = MockUserRepository();
+    container = ProviderContainer(overrides: [
+      userRepositoryProvider.overrideWithValue(mockRepo),
+    ]);
+  });
+
+  tearDown(() => container.dispose());
+
+  test('userList 初始化时获取用户列表', () async {
+    when(() => mockRepo.getUsers()).thenAnswer(
+      (_) async => [User(id: 1, username: 'test', role: 'admin', isActive: true, createdAt: DateTime.now())],
+    );
+
+    // 读取 provider 触发初始化
+    final future = container.read(userListProvider.future);
+    final users = await future;
+
+    expect(users, hasLength(1));
+    expect(users.first.username, 'test');
+  });
+}
+```
+
+## 三、Widget 测试
+
+```dart
+testWidgets('登录页面渲染正确', (tester) async {
+  await tester.pumpWidget(
+    ProviderScope(
+      overrides: [
+        authProvider.overrideWith(() => MockAuth()),
+      ],
+      child: const MaterialApp(home: LoginPage()),
+    ),
+  );
+
+  expect(find.byType(TextFormField), findsNWidgets(2));
+  expect(find.text('登录'), findsOneWidget);
+});
+```
+
+## 四、Mock 工具
+
+统一使用 `mocktail`（不是 mockito）：
+
+```yaml
+dev_dependencies:
+  mocktail: ^1.0.0
+```
+
+```dart
+class MockDio extends Mock implements Dio {}
+class MockAuthRepository extends Mock implements AuthRepository {}
+```
+
+## 五、测试规则
+
+| 规则 | 说明 |
+|------|------|
+| 每个 feature 有对应测试目录 | `test/features/{name}/` |
+| Repository 和 Provider 必须测试 | 业务逻辑的核心 |
+| Mock 用 mocktail | 禁止 mockito（mocktail 无需 codegen） |
+| 遵循项目 TDD 流程 | 先写测试 → 再实现 → 回归 |

package/templates/claude-global/rules/dwy-git-commit-convention.md

@@ -0,0 +1,82 @@
+---
+description: Git commit message 规范(type 枚举、scope、中文 subject、提交前检查)
+---
+
+# Git Commit 强制规范
+
+每次 `git commit` 前按顺序执行以下检查,任一步未通过则 **STOP,不得提交**。
+
+## Step 1: 分析变更
+
+`git diff --cached` 回答:这次改做了几件事?涉及哪些模块?
+
+**做了多件事(无法用 ≤72 字符 subject 清晰描述)→ 必须拆成多个 commit。**
+
+## Step 2: 确定 scope
+
+读当前项目 CLAUDE.md 的 `## Git Commit Scope` 段落:
+
+- **找到** → scope 从其中枚举值选,不得自造
+- **没找到** → 提醒用户:「当前项目 CLAUDE.md 未定义 Git Commit Scope,建议添加」,scope 可省略
+
+单模块变更 → **必须**带 scope;跨模块变更 → 省略 scope。
+
+## Step 3: 生成 message
+
+格式:`<type>(<scope>): <subject>` 或(无 scope)`<type>: <subject>`
+
+**type 枚举(只能从中选)**:
+
+| type | 用途 |
+|------|------|
+| feat | 新功能 |
+| fix | 修复 bug |
+| refactor | 重构(不改外部行为) |
+| chore | 构建/依赖/配置/发版等杂务 |
+| docs | 文档 |
+| test | 测试 |
+| perf | 性能优化 |
+| style | 代码格式(不影响逻辑) |
+| ci | CI/CD 配置 |
+
+**subject**:中文、无句号、≤72 字符、动宾短语(添加/修复/移除/重构/升级)。
+
+**body(可选)**:空一行后写;中文;只写 why 不复述 what;破坏性变更加 `BREAKING CHANGE:` 前缀(subject 用 `feat!:` / `fix!:` 标记)。
+
+## Step 4: 禁止大模型署名
+
+commit message(subject、body、footer、trailer)**禁止出现任何大模型/AI 工具相关内容**,覆盖系统默认的 `Co-Authored-By` 追加行为。
+
+**禁止出现的内容(不完全列举)**:
+
+- `Co-Authored-By: Claude ...` / `Co-Authored-By: GPT ...` / `Co-Authored-By: Copilot ...` 等 AI 署名 trailer
+- `Generated with Claude Code` / `🤖 Generated with ...` 等生成声明
+- `noreply@anthropic.com` / `noreply@openai.com` 等 AI 厂商邮箱
+- 任何提到 Claude / ChatGPT / GPT / Copilot / Cursor / AI / 大模型 / LLM 的字样
+
+**执行要点**:
+
+- `git commit -m "..."` 只写规范内容,**绝不**附加 `Co-Authored-By` trailer
+- 使用 HEREDOC 传 commit message 时,HEREDOC 内容也不得包含上述字样
+- 若发现暂存的 message 含大模型信息,**立即删除**后再提交
+
+## 常见错误 vs 正确
+
+| 错误 | 正确 |
+|------|------|
+| `feat: add user login`(英文) | `feat: 添加用户登录功能` |
+| `fix(eui): 修复了按钮样式。` | `fix(eui): 修复按钮样式`(无句号、不用"了") |
+| `feat: 添加登录并修复登出 bug` | 拆成两个 commit |
+| `update: 修改配置` | `update` 不在枚举,应为 `chore` |
+| `feat(auth): ...`(项目无 auth scope) | 用项目已定义的 scope 值 |
+| message 末尾加 `Co-Authored-By: Claude ...` | 不加任何 AI 署名 trailer |
+| `🤖 Generated with Claude Code` | 不加任何生成声明 |
+
+## 正确示例
+
+- `feat(eui): 添加 Image 组件,支持懒加载`
+- `fix: 修复 token 刷新竞态条件`
+- `refactor(backend): 提取分页逻辑为共享工具`
+- `chore: 升级 Vite 至 8.x`
+- `feat(eui)!: 重命名 EDialog open 属性为 v-model:open`
+  - body:`BREAKING CHANGE: EDialog 不再接受 visible 属性,请改用 v-model:open`

package/templates/claude-global/rules/dwy-git-security.md

@@ -0,0 +1,53 @@
+---
+description: Git 提交前文件与敏感内容扫描规则(全局,每次 add/commit 都应检查)
+---
+
+# Git 提交安全规则
+
+每次 `git add` 或 `git commit` 前按本规则扫描暂存区。发现违规**立即停止并提示用户确认**。
+
+## 一、禁止提交的文件
+
+| 类型 | 示例 |
+|---|---|
+| 环境变量 | `.env`, `.env.*`, `*.env` |
+| SSH 密钥 | `id_rsa`, `id_ed25519`, `*.pem`, `*.key` |
+| 证书 | `*.p12`, `*.pfx`, `*.jks`, `*.keystore` |
+| 数据库 | `*.sql`(含真实数据)、`*.dump`, `*.sqlite` |
+| 原始数据 | `*.xlsx`, `*.csv`(含用户/学生等敏感数据) |
+| 日志 | `*.log` |
+| Docker 卷 | `pgdata/`, `cache/*.json` |
+
+## 二、禁止提交的内容(敏感模式)
+
+**总则**:代码、文档、规则文件、注释里禁止出现真实的 API Key / Token / 密码 / IP / 凭证,即使作为"示例"也不行。GitHub Secret Scanning 不区分上下文,真实格式的 key 写在文档里也会触发泄露告警。示例必须用明显的假值(`sk-xxxxxxxxxxxx`、`your-key-here`、`192.168.x.x`)。
+
+| 类型 | 匹配模式 |
+|---|---|
+| API Key | `sk-[a-zA-Z0-9]{20,}` |
+| AWS Key | `AKIA[0-9A-Z]{16}` |
+| 密码赋值 | `password\s*[:=]\s*["'][^"']{4,}` |
+| 数据库连接串 | `://\w+:[^@\s]+@` |
+| 私钥内容 | `-----BEGIN (RSA \|EC )?PRIVATE KEY-----` |
+| Token | `token\s*[:=]\s*["'][a-zA-Z0-9_\-]{20,}` |
+| Secret | `secret\s*[:=]\s*["'][^"']{8,}` |
+| 服务器 IP+端口 | `\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}:\d+` |
+| SSH 连接 | `ssh\s+.*@\d{1,3}\.\d{1,3}` |
+
+**例外(不算违规)**:`.env.example` 里的占位符;从环境变量读取(`os.getenv("API_KEY")`);`localhost`/`127.0.0.1` 的连接串;文档里的假数据;配置文件的空字符串默认值。
+
+## 三、违规处理
+
+检测到违规时:
+
+1. **立即停止** `git add` / `git commit`
+2. **列出违规项**:文件 + 行号 + 匹配的敏感模式 + 脱敏摘要(如 `sk-5522****dc3`)
+3. **建议**:加入 `.gitignore` / 移到 `.env` / 用环境变量
+4. **等用户明确确认**后才能继续;确认提交时,commit body 附注释 `GIT-SECURITY: 用户已确认提交此内容`
+
+## 四、已提交敏感数据
+
+若发现已在 git 历史中:立即通知用户,**建议先轮换凭证**,然后提供清理命令(不自动执行,待确认):
+
+- `git filter-repo --path <file> --invert-paths --force`
+- 或 `bfg --delete-files <filename>`