# SheetFlow

**Repository Path**: muhongdi/sheet-flow

## Basic Information

- **Project Name**: SheetFlow
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-28
- **Last Updated**: 2026-05-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SheetFlow - 财务报表自动化处理工具

SheetFlow 是一个基于 Python 的财务报表自动化处理工作流引擎，用于整合多个财务数据源，生成标准化的财务报表。

## 功能特性

- **多步骤数据处理**: 5 步标准化处理流程
- **数据关联**: 自动关联回款、付款数据
- **特殊项目处理**: 支持上海印华项目和资金差价项目的特殊数据覆盖
- **利润计算**: 自动计算项目利润和利润率
- **中间结果保存**: 每步处理结果可保存，便于调试
- **配置驱动**: 通过 YAML 配置文件灵活定制

## 项目结构

```
SheetFlow/
├── config/
│   ├── config-v1.yaml          # 主配置文件
│   └── config-override.yaml    # 覆盖配置（可选）
│
├── data/
│   ├── input/                  # 源文件放置目录
│   ├── intermediate/           # 中间结果（调试用）
│   └── output/                 # 最终输出目录
│
├── src/
│   ├── main.py                 # 主入口
│   ├── config_loader.py        # 配置加载
│   ├── file_handler.py         # 文件处理
│   ├── steps/                  # 处理步骤
│   │   ├── step1_normalize.py
│   │   ├── step2_income_join.py
│   │   ├── step3_cost_join.py
│   │   ├── step4_special_override.py
│   │   └── step5_calculations.py
│   ├── utils/                  # 工具模块
│   │   ├── excel_utils.py
│   │   └── logging.py
│   └── models/                 # 数据模型
│       └── data_context.py
│
├── requirements.txt
├── README.md
└── run.bat / run.sh            # 快速启动脚本
```

## 安装

### 1. 克隆仓库

```bash
cd SheetFlow
```

### 2. 创建虚拟环境

```bash
python -m venv .venv
```

### 3. 激活虚拟环境

**Windows:**
```powershell
.venv\Scripts\activate
```

**macOS/Linux:**
```bash
source .venv/bin/activate
```

### 4. 安装依赖

```bash
pip install -r requirements.txt
```

## 使用方法

### 准备输入文件

将以下文件放入 `data/input/` 目录：

1. `1.运营台账.xlsx` - 运营台账（基础数据）
2. `2.回款汇总表.xlsx` - 回款汇总表
3. `3.付款汇总表.xlsx` - 付款汇总表
4. `4.上海印华项目市场客户应收对账单汇总表.xlsx` - 应收对账单
5. `5.资金差价项目应付对账单汇总表.xlsx` - 应付对账单

### 运行处理流程

**完整流程（5个步骤）:**
```bash
python -m src.main
```

**从指定步骤开始:**
```bash
python -m src.main -s 3  # 从第3步开始
```

**只执行特定步骤:**
```bash
python -m src.main -s 2 -e 2  # 只执行第2步
```

**使用覆盖配置:**
```bash
python -m src.main -o config/config-override.yaml
```

**详细日志输出:**
```bash
python -m src.main -v
```

### 快速启动脚本

**Windows:**
```batch
run.bat
```

**macOS/Linux:**
```bash
./run.sh
```

## 配置说明

配置文件位于 `config/config-v1.yaml`，主要配置项包括：

### 文件路径配置
```yaml
files:
  input_dir: "data/input"
  intermediate_dir: "data/intermediate"
  output_dir: "data/output"
```

### Excel 处理配置
```yaml
excel:
  date_format: "%Y-%m-%d"
  date_columns: ["日期", "开票日期", "回款日期"]
  numeric_columns: ["金额", "含税金额", "不含税金额"]
  column_mapping:
    "项目名称": "project_name"
    "客户名称": "customer_name"
```

### 步骤配置
```yaml
steps:
  step1_normalize:
    save_intermediate: true
  step2_income_join:
    save_intermediate: true
    join_key: "project_name"
```

## 处理流程

```
┌─────────────────┐
│  Step 1         │  读取 + 标准化 + 复制运营台账
│  数据标准化     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Step 2         │  关联回款数据
│  收入关联       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Step 3         │  关联付款数据
│  成本关联       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Step 4         │  特殊项目数据覆盖
│  特殊项目处理   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Step 5         │  利润计算 + 汇总统计
│  最终计算       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  财务报表.xlsx  │
└─────────────────┘
```

## 输出结果

最终输出文件位于 `data/output/` 目录：

- `财务报表.xlsx` - 最新版本的报表
- `财务报表_YYYYMMDD.xlsx` - 带日期版本的报表

中间结果位于 `data/intermediate/` 目录（调试用）：

- `step1_base.xlsx`
- `step2_income.xlsx`
- `step3_cost.xlsx`
- `step4_special.xlsx`
- `step5_calculated.xlsx`

## 日志

日志文件默认保存在 `logs/sheetflow.log`，同时输出到控制台。

## 开发指南

### 添加新的处理步骤

1. 在 `src/steps/` 目录创建新的步骤文件
2. 继承基础步骤类（或使用现有模式）
3. 在 `src/main.py` 中注册新步骤
4. 在配置文件中添加步骤配置

### 修改列名映射

编辑 `config/config-v1.yaml` 中的 `excel.column_mapping` 部分：

```yaml
column_mapping:
  "原始列名": "目标列名"
```

## 许可证

MIT License

## 更新日志

### v0.1.0 (2026-03-22)

- 初始版本发布
- 实现 5 步数据处理流程
- 支持配置文件驱动
- 添加中间结果保存功能