npm package: @hyou/flutter-cli
Description: Flutter命令行工具
Author: cjl
Latest version: 1.0.0

# Flutter 命令行工具使用说明

这是一个基于 **Node.js + Commander** 的 Flutter 命令行工具，包含两个主要命令：
- `flutter-build`：用于快速构建 `apk` / `aab`，并按 **应用名 + 版本号 + 日期 + 构建模式 + 环境** 自动重命名输出文件
- `flutter-router`：用于自动扫描项目中的 Dart 文件，生成路由相关文件

---

## 一、功能特性

### flutter-build 命令
* ✅ 支持 `apk` / `aab` 打包
* ✅ 支持 `debug` / `profile` / `release` 编译模式
* ✅ 支持接口环境区分：`test` / `prod`
* ✅ 自动从 `pubspec.yaml` 读取应用名和版本号
* ✅ 自动生成带日期的输出文件名
* ✅ `release` 模式自动开启混淆与符号分离

### flutter-router 命令
* ✅ 自动扫描项目中的 Dart 文件，查找带有 `@RouteE` 注解的类
* ✅ 自动生成路由导入文件：`router.p.dart`
* ✅ 自动生成路由管理文件：`router.r.dart`
* ✅ 支持路由转场动画配置
* ✅ 支持初始路由设置
* ✅ 支持忽略特定路由

---

## 二、前置条件

### 1. 环境要求

* Node.js ≥ 14
* Flutter SDK 已正确安装
* 当前目录必须包含 `pubspec.yaml`

---

## 三、安装方式

### 全局安装

```bash
npm install -g @hyou/flutter-cli
```

### 项目内安装

```bash
npm install @hyou/flutter-cli --save-dev
```

---

## 四、命令行用法

### 1. flutter-build 命令

```bash
flutter-build <type> [options]
```

#### 参数说明

##### 1️⃣ 必填参数

| 参数     | 说明                 |
| ------ | ------------------ |
| `type` | 打包类型：`apk` 或 `aab` |

##### 2️⃣ 编译模式（**必须且只能选择一个**）

| 参数              | 说明         |
| --------------- | ---------- |
| `-d, --debug`   | Debug 模式   |
| `-p, --profile` | Profile 模式 |
| `-r, --release` | Release 模式 |

##### 3️⃣ 接口环境（必填）

| 参数                | 说明                   |
| ----------------- | -------------------- |
| `-e, --env <key>` | 接口环境：`test` 或 `prod` |

### 2. flutter-router 命令

```bash
flutter-router
```

#### 功能说明
- 自动扫描项目中的 Dart 文件，查找带有 `@RouteE` 注解的类
- 生成路由相关文件：
  - `lib/src/router/router.p.dart`：路由页面导入统一管理
  - `lib/src/router/router.r.dart`：路由管理

#### 注解参数

| 参数          | 说明                  | 默认值          |
| ------------- | --------------------- | --------------- |
| `name`        | 路由名称              | 必填            |
| `initialRoute` | 是否为初始路由        | `false`         |
| `transition`  | 转场动画              | `rightToLeft`   |
| `ignore`      | 是否忽略该路由        | `false`         |

#### 注解使用示例

```dart
@RouteE(name: '/home')
class HomePage extends StatelessWidget {
  // ...
}

@RouteE(name: '/detail', transition: 'leftToRight')
class DetailPage extends StatelessWidget {
  // ...
}

@RouteE(name: '/', initialRoute: 'true')
class SplashPage extends StatelessWidget {
  // ...
}
```

---

## 五、使用示例

### 1️⃣ 打包 Debug APK（测试环境）

```bash
flutter-build apk --debug --env test
```

### 2️⃣ 打包 Profile APK（生产环境）

```bash
flutter-build apk --profile --env prod
```

### 3️⃣ 打包 Release AAB（生产环境）

```bash
flutter-build aab --release --env prod
```

### 4️⃣ 生成路由文件

```bash
flutter-router
```

---

## 六、输出文件说明

### 1. flutter-build 命令输出

#### 默认输出目录

```text
build/app/outputs/flutter-apk/
```

#### 文件命名规则

```text
{AppName}_{VersionName}-{VersionCode}_{YYYYMMDD}_{mode}-{env}.{type}
```

#### 示例

```text
MyApp_1.2.0-45_20251224_release-prod.apk
```

##### 命名来源说明

| 字段            | 来源                               |
| ------------- | -------------------------------- |
| `AppName`     | `pubspec.yaml` 中的 `name`（下划线转驼峰） |
| `VersionName` | `version: x.y.z+code` 中的 `x.y.z` |
| `VersionCode` | `version` 中的 `code`              |
| `YYYYMMDD`    | 构建日期                             |
| `mode`        | debug / profile / release        |
| `env`         | test / prod                      |

### 2. flutter-router 命令输出

#### 输出文件

| 文件路径                           | 说明                   |
| -------------------------------- | ---------------------- |
| `lib/src/router/router.p.dart`   | 路由页面导入统一管理    |
| `lib/src/router/router.r.dart`   | 路由管理               |

---

## 七、Release 模式额外行为

当使用 `--release` 时，自动追加以下 Flutter 参数：

```bash
--obfuscate
--split-debug-info=./symbols
```

生成的符号文件位于：

```text
./symbols/
```

---

## 八、常见错误提示

### ❌ 未选择编译模式

```text
请选择编译模式
```

### ❌ 同时选择多个模式

```text
只能选择一种编译模式
```

### ❌ 接口环境错误

```text
请选择正确的接口环境: test | prod
```

### ❌ 非 Flutter 项目目录

```text
请确保当前目录下有pubspec.yaml文件
```

---

## 九、注意事项

* Windows 平台使用的是 `move` 命令重命名文件
* 如需兼容 macOS / Linux，可将 `move` 替换为 `mv`
* 脚本默认只处理 Android 构建产物