# CLI Interface

## Purpose

CLI Interface 定义 yaml2pptx 命令行工具的用户交互界面，包括子命令结构、参数规范、行为约定和错误处理。它确保用户能够通过清晰、一致的命令行接口使用工具的所有功能。

## Requirements

### Requirement: 系统必须使用子命令架构

系统 SHALL 采用子命令架构，提供 check、convert、preview 三个独立子命令，每个子命令有明确的职责。

#### Scenario: 使用 check 子命令验证文件

- **WHEN** 用户运行 `uv run yaml2pptx.py check input.yaml`
- **THEN** 系统验证 YAML 文件并输出验证结果

#### Scenario: 使用 convert 子命令转换文件

- **WHEN** 用户运行 `uv run yaml2pptx.py convert input.yaml`
- **THEN** 系统将 YAML 文件转换为 PPTX 文件

#### Scenario: 使用 preview 子命令启动预览

- **WHEN** 用户运行 `uv run yaml2pptx.py preview input.yaml`
- **THEN** 系统启动预览服务器

#### Scenario: 不提供子命令时显示帮助

- **WHEN** 用户运行 `uv run yaml2pptx.py`
- **THEN** 系统显示帮助信息，列出所有可用子命令

### Requirement: check 子命令必须验证 YAML 文件

系统 SHALL 提供 check 子命令，用于验证 YAML 文件的正确性，输出 ERROR/WARNING/INFO 三级分类的验证结果。

#### Scenario: 基本验证

- **WHEN** 用户运行 `uv run yaml2pptx.py check input.yaml`
- **THEN** 系统验证文件并输出文本格式的验证结果

#### Scenario: 使用模板目录验证

- **WHEN** 用户运行 `uv run yaml2pptx.py check input.yaml --template-dir ./templates`
- **THEN** 系统使用指定的模板目录进行验证

#### Scenario: 验证通过时返回退出码 0

- **WHEN** 验证完成且无错误
- **THEN** 系统返回退出码 0

#### Scenario: 验证失败时返回退出码 1

- **WHEN** 验证发现错误
- **THEN** 系统返回退出码 1

### Requirement: convert 子命令必须转换 YAML 为 PPTX

系统 SHALL 提供 convert 子命令，将 YAML 文件转换为 PPTX 文件，支持自动验证和文件覆盖控制。

#### Scenario: 基本转换（自动生成输出文件名）

- **WHEN** 用户运行 `uv run yaml2pptx.py convert input.yaml`
- **THEN** 系统生成 `input.pptx` 文件

#### Scenario: 指定输出文件名

- **WHEN** 用户运行 `uv run yaml2pptx.py convert input.yaml output.pptx`
- **THEN** 系统生成 `output.pptx` 文件

#### Scenario: 使用模板目录转换

- **WHEN** 用户运行 `uv run yaml2pptx.py convert input.yaml --template-dir ./templates`
- **THEN** 系统使用指定的模板目录进行转换

#### Scenario: 默认自动验证

- **WHEN** 用户运行 `uv run yaml2pptx.py convert input.yaml`
- **THEN** 系统先验证 YAML 文件，发现错误时终止转换

#### Scenario: 跳过自动验证

- **WHEN** 用户运行 `uv run yaml2pptx.py convert input.yaml --skip-validation`
- **THEN** 系统跳过验证，直接转换

#### Scenario: 输出文件已存在时报错

- **WHEN** 输出文件已存在且未使用 --force 参数
- **THEN** 系统报错并提示使用 --force 强制覆盖

#### Scenario: 强制覆盖已存在文件

- **WHEN** 用户运行 `uv run yaml2pptx.py convert input.yaml output.pptx --force`
- **THEN** 系统覆盖已存在的 output.pptx 文件

### Requirement: preview 子命令必须启动预览服务器

系统 SHALL 提供 preview 子命令，启动预览服务器，支持端口配置、主机配置和浏览器控制。

#### Scenario: 基本预览（随机端口）

- **WHEN** 用户运行 `uv run yaml2pptx.py preview input.yaml`
- **THEN** 系统在随机端口（30000-40000）启动预览服务器并自动打开浏览器

#### Scenario: 指定端口

- **WHEN** 用户运行 `uv run yaml2pptx.py preview input.yaml --port 8080`
- **THEN** 系统在端口 8080 启动预览服务器

#### Scenario: 配置主机地址（局域网预览）

- **WHEN** 用户运行 `uv run yaml2pptx.py preview input.yaml --host 0.0.0.0`
- **THEN** 系统在 0.0.0.0 启动服务器，允许局域网访问

#### Scenario: 不自动打开浏览器

- **WHEN** 用户运行 `uv run yaml2pptx.py preview input.yaml --no-browser`
- **THEN** 系统启动服务器但不自动打开浏览器

#### Scenario: 使用模板目录预览

- **WHEN** 用户运行 `uv run yaml2pptx.py preview input.yaml --template-dir ./templates`
- **THEN** 系统使用指定的模板目录进行预览

### Requirement: 系统必须提供 --template-dir 通用参数

系统 SHALL 在所有子命令中提供 --template-dir 参数，用于指定模板文件目录。

#### Scenario: check 命令使用模板目录

- **WHEN** 用户运行 `uv run yaml2pptx.py check input.yaml --template-dir ./templates`
- **THEN** 系统使用指定的模板目录进行验证

#### Scenario: convert 命令使用模板目录

- **WHEN** 用户运行 `uv run yaml2pptx.py convert input.yaml --template-dir ./templates`
- **THEN** 系统使用指定的模板目录进行转换

#### Scenario: preview 命令使用模板目录

- **WHEN** 用户运行 `uv run yaml2pptx.py preview input.yaml --template-dir ./templates`
- **THEN** 系统使用指定的模板目录进行预览

### Requirement: 系统必须验证输入文件存在性

系统 SHALL 在执行任何操作前验证输入文件是否存在，不存在时报错并退出。

#### Scenario: 输入文件不存在时报错

- **WHEN** 用户指定的输入文件不存在
- **THEN** 系统输出错误信息 "输入文件不存在: <文件路径>" 并返回退出码 1

#### Scenario: 输入文件存在时继续执行

- **WHEN** 用户指定的输入文件存在
- **THEN** 系统继续执行相应的子命令操作

### Requirement: 系统必须提供清晰的帮助信息

系统 SHALL 为每个子命令提供清晰的帮助信息，包括参数说明和使用示例。

#### Scenario: 显示全局帮助

- **WHEN** 用户运行 `uv run yaml2pptx.py --help`
- **THEN** 系统显示工具描述和所有可用子命令列表

#### Scenario: 显示子命令帮助

- **WHEN** 用户运行 `uv run yaml2pptx.py check --help`
- **THEN** 系统显示 check 子命令的参数说明和使用示例

### Requirement: 系统必须提供短选项支持

系统 SHALL 为常用参数提供短选项，提升用户体验。

#### Scenario: 使用 -f 作为 --force 的短选项

- **WHEN** 用户运行 `uv run yaml2pptx.py convert input.yaml -f`
- **THEN** 系统强制覆盖已存在文件

#### Scenario: 短选项和长选项等效

- **WHEN** 用户使用 -f 或 --force
- **THEN** 系统行为完全一致