chore: 初始化文档站仓库

dev/bill-fields.md

@@ -0,0 +1,89 @@
+# 账单字段说明
+
+本章说明支付宝「交易记录明细查询」导出的 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)