# 账单字段说明

本章说明支付宝「交易记录明细查询」导出的 CSV 在导入本系统时，各字段的读取与丢弃情况，可作为开发新解析器或调整字段映射的参考。

## 样例与实现位置

- 编码：GBK（解析器兼容 UTF-8 / UTF-8 BOM）
- 解析器：`src/main/java/cn/rosercode/finance/importer/AlipayBillParser.java`
- 落库服务：`src/main/java/cn/rosercode/finance/service/impl/BillImportServiceImpl.java`

## 文件结构

| 位置 | 内容 | 是否处理 |
|---|---|---|
| 第 1 行 | `支付宝交易记录明细查询` | 忽略 |
| 第 2 行 | `账号:[...]` | 忽略 |
| 第 3 行 | `起始日期:[...] 终止日期:[...]` | 忽略 |
| 第 4 行 | `---交易记录明细列表---` | 忽略 |
| 第 5 行 | 表头（以「交易号」开头） | 作为列定位依据 |
| 数据行 | 每行一笔交易 | 逐行解析 |
| 结尾统计 | 待收入/已支出/待支出、导出时间、用户 | 忽略 |

解析器通过「以 `交易号` 开头」定位表头行；遇到空行、`---` 分隔线或 `共` 开头的统计行即结束。

## CSV 完整表头（16 列）

| 序号 | 列名 | 序号 | 列名 |
|---|---|---|---|
| 1 | 交易号 | 9 | 商品名称 |
| 2 | 商家订单号 | 10 | 金额（元） |
| 3 | 交易创建时间 | 11 | 收/支 |
| 4 | 付款时间 | 12 | 交易状态 |
| 5 | 最近修改时间 | 13 | 服务费（元） |
| 6 | 交易来源地 | 14 | 成功退款（元） |
| 7 | 类型 | 15 | 备注 |
| 8 | 交易对方 | 16 | 资金状态 |

## 完全丢弃的字段（7 个）

| 列名 | 说明 |
|---|---|
| 商家订单号 | 未使用 |
| 最近修改时间 | 未使用 |
| 交易来源地 | 未使用 |
| 类型 | 未使用，改用「收/支」推断类型 |
| 服务费（元） | 未使用 |
| 成功退款（元） | 未使用 |
| 备注 | 支付宝自带备注被丢弃；系统备注由「交易对方 · 商品名称」拼接生成 |

## 读取但未落库的字段（3 个）

| 列名 | 用途 |
|---|---|
| 交易状态 | 仅用于类型推断与预览展示 |
| 资金状态 | 仅用于「不计收支」行的类型推断 |
| 交易创建时间 | 仅当「付款时间」为空时作为交易时间兜底 |

## 落库映射（写入 `t_transaction`）

| CSV 列 | 数据库字段 | 说明 |
|---|---|---|
| 交易号 | `external_no` | 导入去重键 |
| 付款时间（缺失时用交易创建时间） | `transaction_time` | 交易发生时间 |
| 金额（元） | `amount` | 去除千分位逗号后解析 |
| 收/支 | `type` + `include_in_stats` | 「不计收支」默认 `include_in_stats = 0` |
| 交易对方 + 商品名称 | `remark` | 拼接为「交易对方 · 商品名称」，截断至 255 字符 |
| — | `channel` | 固定为 `ALIPAY` |
| — | `category_id` | 取用户选择的默认分类；未选择则为 `NULL` |

### 类型推断规则

| 收/支 | 交易状态 / 资金状态 | 推断类型 |
|---|---|---|
| 支出 | — | `EXPENSE` |
| 收入 | — | `INCOME` |
| 不计收支 | 交易状态含「退款」 | `INCOME` |
| 不计收支 | 资金状态为「已收入」 | `INCOME` |
| 不计收支 | 其他（如「交易关闭」） | `EXPENSE` |

## 可能的后续增强

1. 将支付宝「备注」并入系统 `remark`（当前完全丢失）。
2. 新增字段记录「服务费」/「成功退款」。
3. 保留「商家订单号」作为辅助去重或展示。

## 相关文档

- [账单解析](/dev/bill-parsing)
- [支付宝账单（使用文档）](/guide/bills/alipay)