lanyuanxiaoyao
cd7988cbd5
Add core Python script (yaml2pptx.py) for converting YAML to PowerPoint: - Element rendering: text, image, shape, table, chart - Template system with placeholders - PPTX generation with python-pptx OpenSpec workflow setup: - 3 archived changes: browser-preview, template-dir-cli, yaml-to-pptx - 7 main specifications covering all core modules - Config and documentation structure 30 files changed, 4984 insertions(+)
84 lines
3.2 KiB
Markdown
84 lines
3.2 KiB
Markdown
# Template Directory CLI
|
||
|
||
## Purpose
|
||
|
||
提供命令行参数支持，允许用户通过 `--template-dir` 参数明确指定模板文件目录，使脚本可以在任何位置运行而不依赖特定的目录结构。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: 系统必须支持 --template-dir 命令行参数
|
||
|
||
系统 SHALL 提供 `--template-dir` 命令行参数，允许用户指定模板文件目录的路径。
|
||
|
||
#### Scenario: 指定绝对路径的模板目录
|
||
|
||
- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml --template-dir /path/to/templates`
|
||
- **THEN** 系统使用 `/path/to/templates` 作为模板目录
|
||
|
||
#### Scenario: 指定相对路径的模板目录
|
||
|
||
- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml --template-dir ./templates`
|
||
- **THEN** 系统将相对路径解析为相对于当前工作目录（CWD）的绝对路径
|
||
|
||
#### Scenario: Windows 路径格式支持
|
||
|
||
- **WHEN** Windows 用户运行 `uv run yaml2pptx.py input.yaml --template-dir C:\Users\me\templates`
|
||
- **THEN** 系统正确解析 Windows 路径格式
|
||
|
||
#### Scenario: 不指定 template-dir 参数且不使用模板
|
||
|
||
- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml`，且 YAML 文件中所有幻灯片都是自定义幻灯片（不使用模板）
|
||
- **THEN** 系统正常处理，不报错
|
||
|
||
### Requirement: 使用模板时必须指定 template-dir
|
||
|
||
系统 SHALL 在 YAML 文件中使用了模板但未指定 `--template-dir` 参数时报错。
|
||
|
||
#### Scenario: 使用模板但未指定 template-dir
|
||
|
||
- **WHEN** YAML 文件中包含 `template: title-slide`，但用户未提供 `--template-dir` 参数
|
||
- **THEN** 系统抛出错误，提示"未指定模板目录，无法加载模板: title-slide"，并建议使用 `--template-dir` 参数
|
||
|
||
#### Scenario: 错误信息包含使用示例
|
||
|
||
- **WHEN** 系统因未指定 template-dir 而报错
|
||
- **THEN** 错误信息中包含"请使用 --template-dir 参数指定模板目录"的提示
|
||
|
||
### Requirement: 系统必须支持跨平台路径处理
|
||
|
||
系统 SHALL 正确处理 Mac 和 Windows 平台的路径格式，包括路径分隔符和路径表示。
|
||
|
||
#### Scenario: Mac 路径格式
|
||
|
||
- **WHEN** Mac 用户指定 `--template-dir /Users/me/templates`
|
||
- **THEN** 系统正确解析 Unix 风格的路径
|
||
|
||
#### Scenario: Windows 路径格式（反斜杠）
|
||
|
||
- **WHEN** Windows 用户指定 `--template-dir C:\templates`
|
||
- **THEN** 系统正确解析 Windows 风格的路径
|
||
|
||
#### Scenario: Windows 路径格式（正斜杠）
|
||
|
||
- **WHEN** Windows 用户指定 `--template-dir C:/templates`
|
||
- **THEN** 系统正确解析路径（Windows 支持正斜杠）
|
||
|
||
#### Scenario: 相对路径在不同平台
|
||
|
||
- **WHEN** 用户在任意平台指定 `--template-dir ./templates`
|
||
- **THEN** 系统根据当前平台的规则正确解析相对路径
|
||
|
||
### Requirement: 参数帮助信息必须清晰
|
||
|
||
系统 SHALL 在 `--help` 输出中提供清晰的 `--template-dir` 参数说明。
|
||
|
||
#### Scenario: 查看帮助信息
|
||
|
||
- **WHEN** 用户运行 `uv run yaml2pptx.py --help`
|
||
- **THEN** 帮助信息中包含 `--template-dir` 参数的说明，注明"如果 YAML 中使用了模板则必须指定"
|
||
|
||
#### Scenario: 帮助信息包含路径说明
|
||
|
||
- **WHEN** 用户查看 `--template-dir` 的帮助信息
|
||
- **THEN** 说明中注明"可以是绝对路径或相对路径（相对于当前工作目录）"
|