# 读取 Excel 并写入数据列表

服务读取第一张工作表，用首个非空行作为表头，将后续有映射值的行批量新增到指定数据列表。

## 输入和输出

| 配置 ID | 类型 | 用途 |
| --- | --- | --- |
| `Excel file` | 文件 | 一个上传的 Excel 文件。 |
| `Data List ID` | 文本 | 目标列表的数字 ID。使用文本保存，避免长 ID 精度丢失。 |
| `Mapping JSON` | 文本 | Excel 表头与目标列表内部字段名的映射。 |
| `Added Number` | 数值输出 | 服务从 YeeSDK 响应中确认的实际新增数。 |

## 配置步骤

1. 在测试应用中导入 YCS，准备含标题、金额和费用日期的测试列表。
2. 在易企办官网模板中心找到「费用记录列表」，下载 Excel 示例并通过文件变量传入。第一张工作表包含表头和四条虚构记录。
3. 用目标列表实际的内部字段名替换下例的 `Title`、`Decimal1`、`Datetime1`。编码、工号等保留前导零的值，应在 Excel 中使用文本单元格。
4. 将 `Added Number` 映射到后续流程中的数值变量。初次测试时比对目标列表和源文件，再配置后续处理。

```json
[
  { "excelColumn": "费用名称", "fieldName": "Title" },
  { "excelColumn": "金额", "fieldName": "Decimal1" },
  { "excelColumn": "费用日期", "fieldName": "Datetime1" }
]
```

## 写入与异常

列名缺失或重复、重复映射同一目标字段、目标字段不存在或不可写时，服务在写入前停止。空白单元格省略，实际数字和日期按原单元格值转换，日期保留工作簿中的日期。服务运行环境需允许加载原模板使用的 SheetJS 0.20.3 脚本。

服务执行批量新增。若返回数少于预期，或写入响应中断，先核对实际新增记录，再决定需要补录的行。报错信息只描述失败阶段和映射序号。

## 验收范围

文件已通过 YCS 格式验证。用真实的 Excel 示例和固定版本 SheetJS 做了本地解析，并使用模拟 YeeSDK 核对请求、部分成功和失败响应。中国版租户还需确认文件访问、SDK 权限、脚本加载和实际写入结果。