TableProcessing/README.md

# 财务Excel数据处理程序 - 使用说明

## 概述

本程序用于处理财务Excel数据,自动提取收款信息并生成会计分录表。

---

## 前置要求

### 运行环境

- **Python版本**: Python 3.x
- **操作系统**: Windows / Linux / macOS

### 依赖库安装

本程序依赖以下Python第三方包:

#### 1. openpyxl

**用途**: Excel文件读写操作

**安装命令**:

```bash
pip install openpyxl --break-system-packages
```

或使用虚拟环境(推荐):

```bash
# 创建虚拟环境
python3 -m venv venv

# 激活虚拟环境
# Linux/Mac:
source venv/bin/activate
# Windows:
venv\Scripts\activate

# 安装依赖
pip install openpyxl
```

**版本要求**: 建议使用最新稳定版本

#### 验证安装

安装完成后,可以通过以下命令验证:

```bash
python3 -c "import openpyxl; print(openpyxl.__version__)"
```

如果输出版本号(例如: 3.1.2),则说明安装成功。

---

## 功能说明

### 1. 数据提取 (`process_excel.py`)

从Excel文件中提取财务数据并输出为JSON格式。

**输入文件**: `data/data.xlsx` (Sheet1)

**输出文件**: `res.json`

**提取字段**:
- `ReceivedAmount`: 实收金额 (F列)
- `HandlingFee`: 手续费 (G列，空值记为0)
- `Order`: 订单列表
  - `OrderNum`: 订单号 (H列，可以为空)
  - `Amount`: 金额 (I列，必需)
  - `AccountName`: 账户名称 (O列)
- `checkRes`: 验证结果 (实收金额+手续费 = 订单金额之和)

**运行命令**:
```bash
python3 process_excel.py
```

**输出示例**:
```json
[
  {
    "ReceivedAmount": 12125,
    "HandlingFee": 25,
    "Order": [
      {
        "OrderNum": "XLRQD300T25",
        "Amount": 550,
        "AccountName": "24台湾长荣航运"
      }
    ],
    "checkRes": true
  }
]
```

---

### 2. 会计分录生成 (`generate_accounting_entries.py`)

根据`res.json`生成标准会计分录表。

**输入文件**: `res.json`

**输出文件**: `AccountingEntries.xlsx`

**运行命令**:
```bash
python3 generate_accounting_entries.py
```

---

## 会计分录规则

### 基本规则

每笔到账金额产生以下分录:

1. **到账金额 - 借方** (每笔记录1条)
   - 科目代码: `1002.02`
   - 科目名称: `银行存款 - 中行USD`
   - 摘要: `美金收款-{OrderNum}` (如果OrderNum为空,则为 `美金收款`)
   - 币别: 美元
   - 原币金额: ReceivedAmount
   - 金额: ReceivedAmount × 汇率

2. **手续费 - 借方** (如果手续费>0)
   - 科目代码: `5603.03`
   - 科目名称: `财务费用-手续费`
   - 摘要: `美金收款-{OrderNum}` (如果OrderNum为空,则为 `美金收款`)
   - 币别: 人民币
   - 金额: HandlingFee × 汇率

3. **订单明细 - 贷方** (每个Order记录1条)
   - 科目代码: `1122`
   - 科目名称: `应收账款`
   - 应收账款: Order.Amount (显示在"应收账款"列)
   - 摘要: `美金收款-{OrderNum}` (如果OrderNum为空,则为 `美金收款`)
   - 币别: 美元
   - 原币金额: Order.Amount
   - 金额: Order.Amount × 汇率

### 特殊规则

- **摘要处理**:
  - OrderNum有值时: 摘要为 `美金收款-{OrderNum}`
  - OrderNum为空时: 摘要固定为 `美金收款`
- **金额验证**: checkRes为false的记录,所有相关分录行标记为粉红色背景(#FAD1D4)
- **单元格合并**: 同一笔到账金额的所有分录,"到账金额"和"手续费"列会合并显示
- **空值处理**:
  - 订单金额为空的订单会被跳过,不生成贷方分录
  - 订单号(OrderNum)可以为空,允许记录

---

## 汇率配置

程序支持两种方式设置汇率:

### 方法一: 使用汇率文件 (推荐)

在程序目录下创建 `exchange_rate.txt` 文件,文件中只包含汇率数值。

**操作步骤**:

```bash
# 创建汇率文件
echo "7.25" > exchange_rate.txt

# 运行程序,会自动读取该文件中的汇率
python3 generate_accounting_entries.py
```

**输出示例**:
```
从 exchange_rate.txt 读取汇率: 7.25
使用汇率: 7.25
```

**注意事项**:
- 汇率值必须是有效数字
- 汇率范围: 0.1 ~ 100 (超出范围会使用默认汇率)
- 文件格式错误会自动使用默认汇率

### 方法二: 修改程序默认值

编辑 `generate_accounting_entries.py` 文件第13行:

```python
DEFAULT_EXCHANGE_RATE = 7.1072  # 修改此默认值
```

**默认汇率**: 7.1072

**优先级**: 汇率文件 > 程序默认值

---

## 文件说明

| 文件名 | 说明 |
|--------|------|
| `data/data.xlsx` | 原始财务数据Excel文件 |
| `process_excel.py` | Excel数据提取程序 |
| `res.json` | 提取的财务数据(JSON格式) |
| `generate_accounting_entries.py` | 会计分录生成程序 |
| `AccountingEntries.xlsx` | 生成的会计分录表 |
| `exchange_rate.txt` | 汇率配置文件(可选) |
| `analyze_excel.py` | Excel结构分析工具(可选) |

---

## 使用流程

### 标准流程

1. **准备数据**
   ```bash
   # 确保 data/data.xlsx 文件存在
   ```

2. **提取数据**
   ```bash
   python3 process_excel.py
   # 输出: res.json
   ```

3. **生成会计分录**
   ```bash
   python3 generate_accounting_entries.py
   # 输出: AccountingEntries.xlsx
   ```

4. **检查结果**
   - 打开 `AccountingEntries.xlsx`
   - 粉红色背景的行表示金额不匹配,需要核对

---

## 数据验证

### checkRes字段说明

- **true**: 实收金额 + 手续费 = 订单金额之和 (误差<0.01)
- **false**: 金额不匹配,需要人工核对

### 识别问题记录

在 `AccountingEntries.xlsx` 中:
- 粉红色背景(#FAD1D4)的行表示该笔记录金额不匹配
- 建议优先核对这些记录

---

## 常见问题

### Q1: 如何处理合并单元格?

程序自动处理F列的合并单元格:
- 合并单元格: 该区域内所有行属于同一笔记录
- 非合并单元格: 每行单独处理

### Q2: 手续费为空怎么办?

程序自动将空值记为0。

### Q3: 订单号(OrderNum)为空怎么办?

订单号为空是允许的,程序会记录该订单。生成的会计分录摘要会显示为 `美金收款`(而不是 `美金收款-{OrderNum}`)。

### Q4: 订单金额为空怎么办?

金额为空的订单会被跳过,不生成贷方分录。

### Q5: 如何修改汇率?

**推荐方法**: 创建 `exchange_rate.txt` 文件,输入汇率值即可。

```bash
echo "7.25" > exchange_rate.txt
```

**备选方法**: 编辑 `generate_accounting_entries.py` 第13行的 `DEFAULT_EXCHANGE_RATE` 值。

### Q6: Excel列对应关系

| 字段 | Excel列 | 说明 |
|------|---------|------|
| ReceivedAmount | F | 实收金额 |
| HandlingFee | G | 手续费 |
| OrderNum | H | 订单号 |
| Amount | I | 解款金额 |
| AccountName | O | 金蝶名称 |

---

## 输出示例

### res.json 示例
```json
[
  {
    "ReceivedAmount": 9455,
    "HandlingFee": 25,
    "Order": [
      {
        "OrderNum": "XLRQD063M25",
        "Amount": 9480,
        "AccountName": "20 Transsea"
      }
    ],
    "checkRes": true
  }
]
```

### AccountingEntries.xlsx 结构

| 到账金额 | 手续费 | 订单号 | 应收账款 | 金蝶名称 | 摘要 | 借/贷 | 科目代码 | 科目名称 | 核算项目 | 币别 | 汇率 | 原币金额 | 金额 |
|---------|--------|--------|---------|---------|------|-------|----------|----------|----------|------|------|----------|------|
| 9455 | 25 | XLRQD063M25 | | 20 Transsea | 美金收款-XLRQD063M25 | 借 | 1002.02 | 银行存款 - 中行USD | 20 Transsea | 美元 | 7.1072 | 9455 | 67,188.54 |
| (合并) | (合并) | XLRQD063M25 | | | 美金收款-XLRQD063M25 | 借 | 5603.03 | 财务费用-手续费 | | 人民币 | | | 177.68 |
| (合并) | (合并) | XLRQD063M25 | 9480 | 20 Transsea | 美金收款-XLRQD063M25 | 贷 | 1122 | 应收账款 | 20 Transsea | 美元 | 7.1072 | 9480 | 67,366.22 |

---

## 注意事项

1. **数据起始行**: 程序从第2行开始读取(第1行为表头)
2. **汇率固定**: 默认使用固定汇率7.1072,不会从Excel读取
3. **金额精度**: 计算结果保留2位小数
4. **合并单元格**: "到账金额"和"手续费"列会自动合并
5. **背景标记**: checkRes=false的记录用粉红色标记
6. **文件编码**: 所有文件使用UTF-8编码

---

## 更新记录

- **v1.3** - 2025-10-17
  - 支持OrderNum为空的订单记录
  - 修改数据提取逻辑: 允许OrderNum为空,只跳过Amount为空的订单
  - 优化摘要生成: OrderNum为空时摘要显示为 `美金收款`
  - 确保所有数据行都被正确记录和处理

- **v1.2** - 2025-10-17
  - 新增汇率文件支持: 可通过 `exchange_rate.txt` 设置汇率
  - 智能汇率验证: 自动检测异常汇率并回退到默认值
  - 改进错误处理: 汇率文件异常时提供详细提示信息

- **v1.1** - 2025-01-17
  - 优化会计分录规则: 移除"到账金额-贷方"记录
  - 每个Order记录都生成对应的贷方分录
  - Order生成的贷方记录在"应收账款"列显示Amount金额
  - 简化单订单处理逻辑

- **v1.0** - 2025-01-17
  - Excel数据提取
  - 会计分录生成
  - 合并单元格支持
  - 金额验证功能
  - 背景色标记

---

## 联系支持

如遇问题或需要帮助,请检查:
1. Excel文件格式是否正确
2. 列映射是否匹配
3. Python依赖是否已安装
4. 汇率设置是否正确