# Hua.Cli 产品需求文档 (PRD)

## 一、产品概述

### 1.1 产品定位

**Hua.Cli** 是面向 .NET 生态的全局命令行工具（Global .NET CLI Tool），为开发者提供项目脚手架生成和依赖版本管理等基础开发工作流支持。它借鉴 **Volo.Abp.Cli** 的分层插件化架构设计，面向 "Hua" 框架生态的快速开发场景。

### 1.2 产品目标

| 目标 | 描述 |
|---|---|
| 快速创建项目 | 通过预置项目模板，一行命令创建标准化的 .NET 解决方案 |
| 版本管理 | 支持 NuGet 包版本更新 |

### 1.3 参考项目

本项目架构参考 ABP Framework 的命令行工具设计：

| 参考项目 | 路径 |
|---|---|
| Volo.Abp.Cli | `D:\Codes\Abp\abp\framework\src\Volo.Abp.Cli` |
| Volo.Abp.Cli.Core | `D:\Codes\Abp\abp\framework\src\Volo.Abp.Cli.Core` |

---

## 二、用户角色

| 角色 | 场景描述 |
|---|---|
| 后端开发者 | 创建项目、更新依赖版本 |

---

## 三、功能需求

### 3.1 命令体系总览

```
hua <command> [target] [options]
```

| 序号 | 命令名 | 功能描述 | 优先级 |
|---|---|---|---|
| 1 | `help` | 显示帮助信息 | P0 |
| 2 | `new` | 基于模板创建新项目/解决方案 | P0 |
| 3 | `update` | 更新项目 NuGet 包版本 | P0 |

### 3.2 核心命令详细需求

#### 3.2.1 `hua new` — 创建项目

```
hua new <模板名> [选项]

选项:
  -n|--name           解决方案名称
  -o|--output         输出目录
  -t|--template       指定模板名称（默认 app）
  --database-provider 指定数据库提供器 (ef)
  --ui-framework      指定 UI 框架 (mvc / none)
  --connection-string 指定连接字符串
  --create-solution-folder 创建解决方案文件夹
  --dry-run           试运行，不实际创建文件
  --no-random-port    不随机化端口
```

**支持的模板类型：**

| 模板名 | 描述 | 优先级 |
|---|---|---|
| `app` | 标准分层应用（Application / Application.Contracts / Domain / Domain.Shared / EntityFrameworkCore / Web / HttpApi） | P0 |
| `ms` | 微服务解决方案（shared + microservices + gateways + applications + modules） | P0 |

模板使用 .NET 自定义模板机制（`.template.config/template.json`），通过 `dotnet new` 引擎创建项目，`sourceName` 自动替换命名空间和项目名。

#### 3.2.2 `hua update` — 更新依赖

```
hua update [选项]

选项:
  -v|--version        目标版本号
  --dry-run           试运行
```

---

## 四、技术架构

### 4.1 分层架构概览

```
┌──────────────────────────────────────────────────────────┐
│                    Hua.Cli (启动入口)                      │
│  - Program.cs (Main 入口)                                │
│  - HuaCliModule.cs (ABP 模块定义)                         │
│  - Serilog 日志配置 / Autofac DI 容器初始化               │
└──────────────────────┬───────────────────────────────────┘
                       │ 引用
┌──────────────────────▼───────────────────────────────────┐
│                 Hua.Cli.Core (核心逻辑)                    │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│  │ Args         │ │ Commands    │ │ ProjectBuilding     │ │
│  │ (参数解析)    │ │ (命令实现)   │ │ (项目构建流水线)     │ │
│  └─────────────┘ └─────────────┘ └─────────────────────┘ │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│  │ Version      │ │ ProjectModification │ │ Http        │ │
│  │ (版本管理)    │ │ (项目修改引擎)       │ │ (HTTP客户端) │ │
│  └─────────────┘ └─────────────────────┘ └─────────────┘ │
│  ┌─────────────┐ ┌─────────────┐                         │
│  │ Utils       │ │ Configuration │                       │
│  │ (工具类)     │ │ (配置管理)     │                       │
│  └─────────────┘ └─────────────┘                         │
└──────────────────────────────────────────────────────────┘
```

### 4.2 核心设计模式

#### 4.2.1 命令模式 (Command Pattern)

所有操作封装为 `IConsoleCommand` 的实现，通过 `CommandSelector` 实现动态路由：

```
IConsoleCommand 接口:
  - GetUsageInfo()   → 返回使用说明
  - GetShortDescription()  → 返回简短描述
  - ExecuteAsync(CommandLineArgs)  → 执行命令
```

命令在 `HuaCliCoreModule` 的 `ConfigureServices` 中通过 `HuaCliOptions.Commands` 字典注册。

#### 4.2.2 流水线模式 (Pipeline Pattern)

项目构建采用 `ProjectBuildPipeline`：

```
ProjectBuildPipeline
  ├── FileEntryListReadStep          (读取模板文件)
  ├── CreateAppSettingsSecretsStep   (创建密钥文件)
  ├── SolutionRenameStep             (重命名解决方案)
  ├── ProjectReferenceReplaceStep    (替换项目引用)
  ├── TemplateCodeDeleteStep         (删除模板标记)
  ├── DatabaseManagementSystemChangeStep  (数据库适配)
  ├── LicenseCodeReplaceStep         (替换许可证)
  ├── CreateProjectResultZipStep     (打包结果)
  └── ...自定义步骤
```

#### 4.2.3 策略模式 (Strategy Pattern)

- **项目模板**：不同模板通过继承 `TemplateInfo` 基类实现各自的自定义构建步骤

#### 4.2.4 依赖注入 (DI)

- 通过 ABP 的 `ITransientDependency` / `ISingletonDependency` 接口实现自动注册
- 使用 Autofac 作为 DI 容器
- 所有服务均按约定自动注册，无需手动配置

### 4.3 启动流程

```
Program.Main(args)
  → Serilog 日志配置（文件 + 控制台双输出）
  → AbpApplicationFactory.Create<HuaCliModule>()
  → application.Initialize()
  → CliService.RunAsync(args)
    → CommandLineArgumentParser.Parse(args)
      → 解析命令名、目标、选项
    → 版本检查（非 Debug 模式）
    → CommandSelector.Select(args)        (选择命令)
    → DI 容器解析命令实例
    → command.ExecuteAsync(args)          (执行命令)
```

### 4.4 项目结构规划

参照 Volo.Abp.Cli 的两个程序集分离设计：

```
Hua.Cli/
├── Hua.Cli.sln
│
├── src/
│   ├── Hua.Cli/                          # 启动入口项目
│   │   ├── Hua.Cli.csproj                # OutputType: Exe, PackAsTool, ToolCommandName: hua
│   │   ├── Program.cs                    # Main 入口
│   │   └── Hua/
│   │       └── Cli/
│   │           └── HuaCliModule.cs        # ABP 模块定义
│   │
│   └── Hua.Cli.Core/                     # 核心逻辑类库
│       ├── Hua.Cli.Core.csproj
│       └── Hua/
│           └── Cli/
│               ├── HuaCliCoreModule.cs           # 核心模块（注册所有命令）
│               ├── CliService.cs                 # 核心服务（命令路由主引擎）
│               ├── CliConsts.cs                  # 全局常量
│               ├── CliPaths.cs                   # 文件路径常量 (~/.hua/cli/)
│               ├── CliUrls.cs                    # API 端点 URL
│               ├── HuaCliOptions.cs              # CLI 全局选项（命令注册字典）
│               ├── CliUsageException.cs          # 命令使用异常
│               │
│               ├── Args/                         # 命令行参数解析
│               │   ├── CommandLineArgs.cs
│               │   ├── CommandLineArgumentParser.cs
│               │   ├── ICommandLineArgumentParser.cs
│               │   └── HuaCommandLineOptions.cs
│               │
│               ├── Commands/                     # 命令实现
│               │   ├── IConsoleCommand.cs
│               │   ├── ICommandSelector.cs
│               │   ├── CommandSelector.cs
│               │   ├── HelpCommand.cs
│               │   ├── NewCommand.cs
│               │   └── UpdateCommand.cs
│               │
│               ├── Configuration/                # 配置读取
│               │   ├── HuaCliConfig.cs
│               │   ├── IConfigReader.cs
│               │   └── ConfigReader.cs
│               │
│               ├── Http/                         # HTTP 客户端
│               │   ├── CliHttpClientFactory.cs
│               │   └── CliHttpClientHandler.cs
│               │
│               ├── ProjectBuilding/              # 项目构建引擎（核心）
│               │   ├── Building/
│               │   │   ├── Steps/                # 构建步骤
│               │   │   ├── ProjectBuildPipeline.cs
│               │   │   ├── ProjectBuildContext.cs
│               │   │   ├── ProjectBuildPipelineStep.cs
│               │   │   └── TemplateProjectBuildPipelineBuilder.cs
│               │   ├── Events/                   # 构建事件
│               │   ├── Files/                    # 文件条目模型
│               │   ├── Templates/                # 模板定义
│               │   │   └── App/AppTemplate.cs
│               │   ├── TemplateProjectBuilder.cs
│               │   ├── TemplateInfoProvider.cs
│               │   └── ISourceCodeStore.cs
│               │
│               ├── ProjectModification/          # 项目修改工具
│               │   └── NugetPackagesVersionUpdater.cs
│               │
│               ├── Utils/                        # 工具类
│               │   ├── CmdHelper.cs
│               │   ├── ConsoleHelper.cs
│               │   └── PathHelper.cs
│               │
│               └── Version/                      # 版本管理
│                   ├── CliVersionService.cs
│                   ├── PackageVersionCheckerService.cs
│                   └── LatestVersionInfo.cs
│
├── test/
│   └── Hua.Cli.Tests/                    # 单元测试项目
│       ├── Hua.Cli.Tests.csproj
│       └── ...
│
└── templates/                             # 项目模板文件
    └── app/
```

### 4.5 技术栈

| 分类 | 技术/组件 | 说明 |
|---|---|---|
| 目标框架 (CLI入口) | .NET 9.0 | 启动项目 TargetFramework |
| 目标框架 (Core) | .NET Standard 2.0/2.1 + .NET 8.0 + .NET 9.0 | 兼容多框架 |
| DI 容器 | Autofac (Volo.Abp.Autofac) | 模块化的依赖注入 |
| 日志 | Serilog | 结构化日志 |
| 命令行解析 | 自研 CommandLineArgumentParser | 类似 System.CommandLine |
| HTTP | IHttpClientFactory + Polly | HTTP 客户端 + 重试策略 |
| JSON | Newtonsoft.Json / System.Text.Json | JSON 序列化 |
| 压缩 | SharpZipLib | ZIP 解压（模板下载） |
| 模板引擎 | 自研文件替换引擎 | 模板变量替换 |
| NuGet | NuGet.Versioning + NuGet.Protocol | 包版本管理 |
| 测试框架 | xUnit + NSubstitute + Shouldly | 单元测试 |

---

## 五、非功能需求

### 5.1 性能要求

| 指标 | 要求 |
|---|---|
| 命令冷启动时间 | < 3 秒 |
| `new` 命令执行时间 | < 30 秒（标准 app 模板） |
| 内存占用 | < 200 MB |

### 5.2 跨平台

- Windows 10+
- macOS 12+
- Linux (Ubuntu 20.04+, Debian 11+)

### 5.3 可用性

- 支持彩色终端输出（ANSI 颜色码）
- 命令执行进度指示（Spinner / 进度条）
- 详细的错误信息和解决建议
- 完善的 `--help` 文档和实例

### 5.4 可扩展性

- 通过 `IConsoleCommand` 接口，新增命令只需实现接口 + DI 注册
- 通过 `ProjectBuildPipelineStep` 基类，新增构建步骤只需实现基类
- 通过 `TemplateInfo` 基类，新增项目模板只需继承并实现自定义步骤

---

## 六、项目规划

### 6.1 开发阶段

| 阶段 | 内容 | 预计产出 |
|---|---|---|
| **P0 - 基础框架** | 项目结构搭建，模块定义，CliService 主引擎，CommandLineArgumentParser，Help 命令，new 命令（app 模板），update 命令，项目构建流水线核心，NuGet 包版本更新 | 可运行的基本 CLI 工具 |

### 6.2 关键依赖方

| 依赖方 | 依赖内容 |
|---|---|
| Hua.Templates | 项目模板仓库（远端或内嵌） |

---

## 七、风险与约束

| 风险/约束 | 影响 | 应对策略 |
|---|---|---|
| ABP 框架版本升级 | 模块 API 不兼容 | 锁定 ABP 主版本，定期同步升级 |
| .NET SDK 版本依赖 | 用户需要安装特定 SDK | 明确版本要求，自动检测并提示 |
| 模板仓库可用性 | 离线环境无法下载模板 | 支持内嵌模板 + 本地缓存机制 |

---

## 八、术语表

| 术语 | 说明 |
|---|---|
| CLI Tool | .NET Global Tool，通过 `dotnet tool install -g` 安装 |
| Project Building Pipeline | 项目构建流水线，多个 Step 串联执行的构建过程 |
| Template | 项目模板，包含完整的解决方案文件结构和代码骨架 |