jp-payroll-conversion-tool/INSTRUCTIONS.md

# 工资明细转换工具 - 使用和维护指南

## 快速开始

1. 确保已安装 Python 3.7 或更高版本
2. 创建虚拟环境并安装依赖:
   ```
   cd excel_converter
   uv venv
   .venv\Scripts\activate  # Windows
   uv pip install -r requirements.txt
   ```
3. 运行应用程序:
   ```
   python main.py
   ```
   或直接双击 `run.bat` 文件

## 目录结构

```
excel_converter/
├── app.py          # 主应用程序代码
├── config.py       # 配置文件
├── main.py         # 入口点
├── requirements.txt # 依赖列表
├── run.bat         # Windows 运行脚本
├── README.md       # 项目说明
├── INSTRUCTIONS.md # 使用和维护指南
└── test_data/      # 测试数据目录
    ├── README.md   # 测试数据说明
    └── sample_format.md # 示例格式文档
```

## 配置指南

### 修改模板路径

如果需要更改模板文件路径，请编辑 `config.py` 文件中的 `TEMPLATE_PATH` 变量。

### 修改单元格映射关系

单元格映射关系在 `config.py` 文件中的 `CELL_MAPPINGS` 字典中定义。格式为:
```python
{
    (源文件sheet索引, 行, 列): (目标文件sheet索引, 行, 列)
}
```

例如，要添加新的映射，可以添加新的键值对:
```python
(0, 5, 3): (0, 5, 5)  # 源文件Sheet1的C5映射到目标文件Sheet1的E5
```

### 修改公司和银行列表

编辑 `config.py` 文件中的 `COMPANY_OPTIONS` 和 `BANK_OPTIONS` 列表即可添加或删除选项。

## 常见问题解决

### 问题1: 程序启动失败

- 检查 Python 版本是否兼容 (3.7+)
- 确认所有依赖已正确安装
- 检查模板文件是否存在于指定路径

### 问题2: 转换后的文件格式不正确

- 确认模板文件格式无误
- 检查输入文件是否符合要求的格式
- 确认映射关系配置正确

### 问题3: 无法识别日期

如果程序无法正确识别日期格式，可能需要在 `app.py` 的 `process_file` 方法中添加更多的日期解析逻辑，支持不同的日期格式。

## 维护和扩展

### 添加新功能

如需添加新功能，请考虑以下几点:
1. 尽量将配置参数放在 `config.py` 文件中
2. 保持用户界面简洁直观
3. 添加适当的错误处理和用户反馈

### 代码维护

- 定期更新依赖包版本
- 如果更改了核心功能，请更新文档
- 考虑添加单元测试以确保功能正常

## 联系与支持

如有问题或需要支持，请联系项目维护者。