ZAR压缩包操作类

RySoftware

DESIGN.md:
# ZAR 归档模块 架构设计文档
版本：V1.0
日期：2026

## 1. 项目概述
ZAR 是一套基于 ARP(RyArchive) 引擎封装的自定义归档系统，用于高效管理多文件与目录结构的打包、存储、读取、解压。

设计目标：
- 上层接口简洁稳定
- 内部结构分层解耦
- 路径处理统一规范
- 支持大文件、多文件批量操作
- 可跨语言对接（C++ / 易语言）

## 2. 系统四层架构

### 2.1 第一层：对外接口层（API Layer）
**职责**
提供统一、稳定、无业务侵入的外部调用入口。
所有上层业务仅依赖该层。

**主要接口**
- 创建压缩包
- 打开压缩包
- 关闭压缩包
- 压缩保存 / 压缩保存Ex
- 解压释放 / 解压释放Ex
- 取文件列表
- 文件/目录存在判断
- 删除包内条目
- 获取包内文件长度

**特点**
- 无复杂逻辑
- 仅做参数校验与状态判断
- 向下调用业务逻辑层

---

### 2.2 第二层：业务逻辑层（Business Layer）
**职责**
模块核心中枢，实现所有归档业务流程。

**核心功能**
- 文件列表遍历与过滤
- 基准目录剥离，生成相对路径
- 自动构建目录树结构
- 区分目录项与文件项
- 批量计数与进度计算
- 解压时先重建目录再写入文件
- 包内索引管理与遍历

**流程**
压缩：
文件列表 → 路径处理 → 构建目录 → 写入目录项 → 写入文件项 → 保存

解压：
读取包索引 → 拆分目录与文件 → 重建目录 → 依次写入文件

---

### 2.3 第三层：路径适配层（Path Adapt Layer）
**职责**
统一所有路径格式，消除路径风格差异。

**核心处理**
- 统一 `/` 与 `\` 为 Windows 标准反斜杠
- 自动补全目录末尾斜杠
- 格式化重复斜杠
- 路径合法性修正
- 保证底层引擎识别一致性

---

### 2.4 第四层：底层引擎层（Engine Layer / ARP）
**职责**
执行真实磁盘 IO、索引读写、压缩解压算法。

**核心能力**
- 归档文件创建、打开、保存、关闭
- 包内数据项写入与读取
- 索引结构管理
- 压缩算法调用
- 二进制数据存储

## 3. 模块依赖关系
接口层 → 业务逻辑层 → 路径适配层 → ARP 引擎层

## 4. 数据流向
外部调用 → 接口校验 → 业务处理 → 路径规范化 → 底层IO → 结果返回

## 5. 设计原则
- 高内聚低耦合
- 接口稳定，内部可重构
- 路径统一优先
- 引擎与业务分离
- 支持扩展新压缩算法
- 支持进度回调与状态反馈

1184798949

感谢分享