# ParqForge 项目路线图

本文档记录项目当前能力、架构边界和后续迭代优先级。README 只面向用户，提供功能介绍、安装和使用说明；项目规划以本文档为准。

最后更新：2026-07-19

## 当前定位

ParqForge 是一个面向 Parquet 文件和 Hive 分区数据集的只读工具集，包含：

- `parqforge-core`：跨平台数据源发现、Parquet metadata 读取、schema 和行数据读取。
- `pqx`：适合终端、管道和脚本使用的 CLI。
- `ParqForge Desktop`：Windows 优先的图形化查看器。

当前架构以读取和预览为主，尚未引入 Parquet 写入、转换或 SQL 执行引擎。

## 已完成

### CLI

- `inspect`：合并原 `schema` 和 `info`，展示列名、类型、nullable、数据/分区字段、压缩、编码、行数、row groups、文件数和分区信息。
- `tree`：以树形结构查看单文件或分区目录中的 Parquet 文件，显示文件大小和创建时间。
- `head`：查看前 N 行。
- `tail`：查看后 N 行。
- `cat`：查看前后数据，中间过长时省略。
- 所有数据行号统一从 1 开始。
- Bash、Zsh、Fish、PowerShell、Elvish Shell 补全脚本生成。
- 支持单个 `.parquet` 文件和 Hive 分区目录（`key=value/`）。

### GUI 和分发

- 单文件和分区目录打开。
- 分区树浏览、数据表格和 Schema/metadata 查看。
- 表格搜索过滤、主题设置和中英文界面。
- `.parquet` 文件关联、开始菜单快捷方式和 CLI PATH 配置。
- Windows MSI 和便携版 bundle。
- Linux/macOS CLI 预编译包、Windows GUI/CLI 合并包及 SHA256 校验清单。
- About 页面更新检查。

## 优先级计划

### P0：查询和质量检查

#### `query`：列选择和条件过滤

目标是提供轻量级数据查询能力，而不是立即引入完整 SQL：

```text
pqx query data.parquet --select col1,col2 --where "age > 18"
```

建议分阶段实现：

1. 列选择。
2. 基础条件过滤。
3. 分区裁剪。
4. 可选排序和输出行数限制。

需要先确定表达式语法、类型转换规则和错误提示格式。

#### `check`：数据集完整性检查

建议检查：

- Parquet 文件是否可读取。
- 分区目录结构是否一致。
- 各文件 schema 是否一致。
- 是否存在空文件、异常文件或缺失分区字段。

该功能可以复用现有 `DataSource` 和 schema 读取逻辑，并为 CI/批处理提供非零退出码。

### P1：结构化输出和可扩展预览

#### 结构化输出

为 `inspect`、`tree`、`head` 等命令增加 JSON、CSV 或 JSONL 输出，方便脚本和数据管道使用：

```text
pqx inspect data.parquet --format json
pqx head data.parquet --format csv
```

#### 预览能力整理

当前 `head`、`tail`、`cat` 已覆盖基本预览需求，不建议简单重复增加 `preview` 命令。只有在加入采样、列选择、过滤或分区裁剪后，才考虑将其设计为更高级的统一入口。

#### 大数据集性能

- 并行读取多个文件 metadata。
- 为 `inspect` 提供可选的快速模式，跳过完整行数统计。
- 评估 metadata 缓存。
- 改进超大目录的 tree 输出和分页体验。

### P2：写入、转换和优化

#### `convert`：格式转换和 Parquet 写入

目标示例：

```text
pqx convert input.csv output.parquet
pqx convert input.parquet output.parquet --compression zstd
```

该阶段需要处理写入、类型推断、压缩配置、错误恢复和输出覆盖策略，复杂度明显高于当前只读架构。

#### `optimize`：数据集优化

在写入能力稳定后再实现：

- 重压缩。
- 小文件合并。
- row group 大小调整。
- 分区重组。
- 编码策略优化。

`optimize` 应建立在 `convert` 的写入管线上，不建议提前实现独立版本。

## 技术债务和基础能力

以下问题不一定表现为独立 CLI 命令，但会影响后续功能：

- 嵌套 Parquet schema 的列映射目前仍是近似实现。
- 分区字段当前统一按 `Utf8` 处理，尚未进行类型推断。
- CLI 自动化测试仍较少，需要增加命令输出和错误场景测试。
- 大数据集统计和多文件 metadata 读取需要进一步评估性能。
- 在引入写入功能前，需要明确覆盖、临时文件和原子替换策略。

## 暂不计划

- Windows CMD 原生补全：缺少统一的标准补全脚本机制，PowerShell 已覆盖 Windows 主流场景。
- CLI 自动修改用户 Shell 配置：涉及权限、已有配置和安全策略，保持由用户显式加载补全脚本。
- 在没有明确查询语义前直接引入完整 SQL 引擎。