chore: 初始化文档站仓库

guide/bills/alipay.md

@@ -0,0 +1,63 @@
+# 支付宝账单
+
+支付宝支持导出「交易记录明细」，系统以 **CSV** 或 **zip** 形式导入。
+
+## 如何获取
+
+### 手机 App（推荐）
+
+1. 打开支付宝 App，进入 **我的 → 账单**。
+2. 点击账单页面右上角的「**…**」，选择「**开具交易流水证明**」（部分版本显示为「开具银行流水证明」）。
+3. 选择证明用途（如「用于材料证明」），点击「申请」，输入支付密码完成验证。
+4. 设置交易流水范围（全部 / 收入 / 支出）与时间范围：可选 1 个月、3 个月或自定义，**最长支持 1 年**，跨年度需分多次申请。
+5. 填写接收账单的**电子邮箱**并确认发送，账单会以压缩包形式发送到邮箱。
+
+### 电脑网页版
+
+访问支付宝官网（www.alipay.com）→ 服务大厅 → 自助服务 → 应用服务 → 收支明细证明，按提示申请。
+
+> 支付宝导出的压缩包通常未加密，可直接交给系统解析；若设置了密码，在导入时输入。
+
+## 导入
+
+在[账单导入](/guide/transactions)页选择账单类型「支付宝」，上传 CSV 或 zip 文件。
+
+- 支持格式：`.csv`、`.zip`
+- 编码：自动识别 UTF-8 / UTF-8 BOM / GBK
+
+## 字段映射
+
+解析器以「交易号」开头的表头行定位数据区，读取以下关键字段：
+
+| 源字段（CSV 列） | 落库字段 | 处理说明 |
+|---|---|---|
+| 交易号 | `external_no` | 导入去重键（`uk_user_external`） |
+| 付款时间 | `transaction_time` | 交易时间；为空时回退「交易创建时间」 |
+| 交易创建时间 | `transaction_time` | 仅作付款时间缺失时的兜底 |
+| 金额（元） | `amount` | 去除千分位逗号后解析 |
+| 收/支 | `type` | 支出→EXPENSE，收入→INCOME |
+| 交易对方 | `remark` | 与商品名称拼接为「交易对方 · 商品名称」，截断至 255 字符 |
+| 商品名称 | `remark` | 同上 |
+| 交易状态 | 仅推断/预览 | 参与类型推断与预览展示，不落库 |
+| 资金状态 | 仅推断 | 用于「不计收支」行的类型推断 |
+| 收/支=不计收支 | `include_in_stats` | 默认不计入统计 |
+| — | `channel` | 固定为 `ALIPAY` |
+| — | `category_id` | 取导入面板默认分类；未选为 NULL |
+
+以下列**完全丢弃**：商家订单号、最近修改时间、交易来源地、类型、服务费（元）、成功退款（元）、备注（支付宝自带备注）。
+
+### 类型推断
+
+| 收/支 | 交易状态 / 资金状态 | 推断类型 |
+|---|---|---|
+| 支出 | — | EXPENSE |
+| 收入 | — | INCOME |
+| 不计收支 | 含「退款」 | INCOME |
+| 不计收支 | 资金状态为「已收入」 | INCOME |
+| 不计收支 | 其他（如交易关闭） | EXPENSE |
+
+## 注意事项
+
+- 支付宝 CSV 中自带的「备注」列不会被导入，系统备注由「交易对方 · 商品名称」拼接生成。
+- 建议按年或按季度导出，避免单文件过大。
+- 重复导入同一文件时，相同交易号的记录会被跳过。

guide/bills/bocom.md

@@ -0,0 +1,51 @@
+# 交通银行账单
+
+交通银行支持导出「交易明细列表」，系统以 **xls** 或 **zip** 形式导入。
+
+## 如何获取
+
+### 手机 App（个人）
+
+1. 打开交通银行 App，在首页点击「**我的账户**」。
+2. 选择需要导出的银行卡，点击「**明细清单**」。
+3. 点击「**发送至邮箱**」，选择时间范围后，交易明细会以电子版发送到指定邮箱。
+4. 导出文件通常为 **Excel（xls）**，并可能以加密压缩包形式发送，解压密码以银行提示为准。
+
+时间范围最长可选 1 年，数据量较大时建议分批次导出。
+
+### 电脑端
+
+登录交通银行个人网银，在账户明细查询中导出交易明细；企业网银可通过「对账单管理」下载。
+
+## 导入
+
+在[账单导入](/guide/transactions)页选择账单类型「交通银行」，上传 xls 或 zip 文件。
+
+- 支持格式：`.xls`、`.zip`
+
+## 字段映射
+
+系统以「记账日期」定位表头，读取以下列：
+
+| 源字段（xls 列） | 落库字段 | 处理说明 |
+|---|---|---|
+| 交易时间 | `transaction_time` | 缺失时回退记账日期 |
+| 记账日期 | `transaction_time` | 仅作兜底 |
+| 对方户名 | `remark` | 作为备注 |
+| 摘要 | `remark` | 与对方户名拼接/作为商品名称 |
+| 支出金额 | `amount` + `type` | 支出列有值时 type=EXPENSE |
+| 收入金额 | `amount` + `type` | 收入列有值时 type=INCOME |
+| 余额 | 仅生成去重键 | 参与 `BOCOM_日期_时分秒_类型_金额` 去重键 |
+| — | `channel` | 固定为 `BOCOM` |
+| — | `category_id` | 取导入面板默认分类；未选为 NULL |
+
+「--」等占位符会被视为空值。
+
+## 去重
+
+交通银行流水没有交易号，系统会以「日期 + 时分秒 + 类型 + 金额」生成稳定的去重键（如 `BOCOM_20260916_082932_收入_3406.50`）。
+
+## 注意事项
+
+- 导出时请选择系统支持的日期范围，单次导出过大时可分多次。
+- 若导出为加密压缩包，导入时需输入密码。

guide/bills/cmb.md

@@ -0,0 +1,81 @@
+# 招商银行账单
+
+招商银行支持导出「交易流水」，系统以 **CSV**、**PDF** 或 **zip** 形式导入。
+
+## 如何获取
+
+招商银行提供多种导出渠道，格式与可查询时间范围各不相同，可按需选择。
+
+### 手机 App（个人，常用）
+
+- 打开招商银行 App，在首页搜索「**流水打印**」或「**打印流水**」，或在 **我的 → 全部** 中找到「流水打印」。
+- 选择账户与时间范围，输入接收邮箱提交。
+- **通过 App 导出的通常是带电子印章的 PDF**，适用于个人对账或证明材料。
+- App 可查询较长时间范围（最长近 5 年），但**单次申请跨度一般不超过 1 年**，更早记录需分次申请。
+- 导出的文件为加密压缩包，解压密码在 App 的「**申请记录**」页查看。
+
+### 个人网银专业版 / 个人银行 PC 版（可导出 Excel）
+
+- 登录个人银行 PC 版（专业版），进入 **账户管理 → 活期交易查询**。
+- 选择时间段查询后点击「保存」，文件类型选择 **Excel(.xls)**。
+- **仅支持查询近 13 个月**的交易记录，且仅支持中文活期交易记录；更早的流水需改用 App 或前往网点。
+
+### 营业网点
+
+- 携带有效身份证件与一卡通，可打印**开户至今**的流水；13 个月以内通常免费，13 个月以上部分网点可能收费。
+- 如需要更早时间且为 Excel 格式，可向柜员明确提出「定制导出电子表格」的需求。
+
+### 企业网银 / 企业手机 App
+
+- 企业网银：**账务管理 → 账务查询 → 交易查询 → 导出 → Excel 快速导出**（可查近 5 年，单次跨度不超过 366 天）。
+- 企业手机 App：首页 → 收支明细 → 右上角下载 → 选择账号与起止日期 → 输入邮箱接收 Excel。
+
+## 导入
+
+在[账单导入](/guide/transactions)页选择账单类型「招商银行」，上传 CSV、PDF 或 zip 文件。
+
+- 支持格式：`.csv`、`.pdf`、`.zip`
+- CSV 与 PDF 使用同一套去重键，两种格式可以混用而不重复导入。
+
+## 字段映射
+
+### CSV
+
+| 源字段（CSV 列） | 落库字段 | 处理说明 |
+|---|---|---|
+| 交易日期 | `transaction_time` | 与交易时间组合为完整时间 |
+| 交易时间 | `transaction_time` | 同上 |
+| 交易备注 | `remark` | 作为备注 |
+| 交易类型 | `remark` / 预览 | 作为商品名称或交易状态 |
+| 收入金额 | `amount` + `type` | 有值时 type=INCOME |
+| 支出金额 | `amount` + `type` | 有值时 type=EXPENSE |
+| 余额 | 生成去重键 | 参与 `CMB_日期_类型_金额_余额` |
+| — | `channel` | 固定为 `CMB` |
+| — | `category_id` | 取导入面板默认分类；未选为 NULL |
+
+`#` 开头的行视为元信息/合计并结束解析。
+
+### PDF
+
+PDF 为文本型「交易流水」，系统按字符坐标还原表格，读取列：
+
+| 源字段 | 落库字段 | 处理说明 |
+|---|---|---|
+| 记账日期 | `transaction_time` | 取零点 |
+| 交易金额 | `amount` + `type` | 带符号单列：负数为支出、正数为收入 |
+| 联机余额 | 生成去重键 + 校验 | 参与去重键；按余额连续性校验（误差 0.005），不连续则标记为不可导入 |
+| 交易摘要 / 对手信息 | `remark` | 作为备注 |
+| — | `channel` | 固定为 `CMB` |
+| — | `category_id` | 取导入面板默认分类；未选为 NULL |
+
+## 去重
+
+银行流水通常没有交易号，系统会以「日期 + 类型 + 金额 + 余额」生成稳定的去重键（如 `CMB_20260916_支出_3406.50_43233.20`），因此重复导入同一账单不会产生重复记录。
+
+## 注意事项
+
+- 系统支持导入招商银行的 **CSV** 与 **PDF**（文本型），优先推荐 CSV。
+- 若导出为加密压缩包，导入时需输入密码（密码见 App「申请记录」页）。
+- PDF 账单请使用招商银行 App 导出的文本型 PDF，扫描件无法解析。
+- **个人网银专业版导出的 `.xls` 暂不支持直接导入**：可在 Excel 中另存为 CSV 后再导入，或改用 App 导出 PDF。
+- 招行 CSV 与 PDF 使用同一套去重键，两种格式可混用而不重复导入。

guide/bills/jd.md

@@ -0,0 +1,47 @@
+# 京东账单
+
+京东支持导出「交易流水」，系统以 **CSV** 或 **zip**（加密压缩包）形式导入。
+
+## 如何获取
+
+1. 打开**京东 App**，进入 **我的 → 设置 → 账单**。
+2. 点击右上角「**…**」，选择「**账单导出**」。
+3. 设置**接收邮箱**，点击「**确定并提交**」，账单会发送到该邮箱。
+4. 从邮件中下载导出的 **CSV** 文件；通常打包为 **zip** 并加密，**解压密码见邮件说明**。
+
+::: tip 以实际界面为准
+京东导出入口可能随 App 版本调整，如界面有差异，可在京东帮助中心搜索「账单导出」。
+:::
+
+## 导入
+
+在[账单导入](/guide/transactions)页选择账单类型「京东」，上传 CSV 或 zip 文件。
+
+- 支持格式：`.csv`、`.zip`
+- 若为加密压缩包，解析时会提示输入解压密码。
+
+## 字段映射
+
+系统以「交易时间」定位表头，读取以下列：
+
+| 源字段（CSV 列） | 落库字段 | 处理说明 |
+|---|---|---|
+| 交易时间 | `transaction_time` | `yyyy-MM-dd HH:mm:ss` |
+| 商户名称 | `remark` | 与交易说明拼接为备注 |
+| 交易说明 | `remark` | 商品/交易描述 |
+| 金额 | `amount` | 支出金额（部分退款已剔除） |
+| 交易状态 | 仅推断/预览 | 如「交易成功」「还款成功」 |
+| 收/支 | `type` + `include_in_stats` | 支出→EXPENSE，收入→INCOME，不计收支→不计入统计 |
+| 交易订单号 | `external_no` | 导入去重键（去除空白） |
+| 收/付款方式 | 仅存原始数据 | 如京东白条、京东小金库、储蓄卡 |
+| 交易分类 | 仅存原始数据 | 如其他网购、白条、小金库 |
+| 商家订单号、备注 | 仅存原始数据 | 不落库 |
+| — | `channel` | 固定为 `JD` |
+| — | `category_id` | 取导入面板默认分类；未选为 NULL |
+
+## 注意事项
+
+- **不计收支行**：白条还款、小金库转入、全额退款等记为「不计收支」，导入后**不计入统计**且默认**不勾选**，可按需手动勾选。
+- **白条消费与还款**：用京东白条消费时，购买记录为「支出」，后续「白条还款」为「不计收支」，不会重复计入支出。
+- **避免重复记账**：京东快捷支付可能同时在银行账单产生记录，请按来源设置「计入统计」，避免重复统计。
+- **去重**：系统按「用户 + 交易订单号」去重，重复导入同一账单会被自动跳过。

guide/bills/meituan.md

@@ -0,0 +1,38 @@
+# 美团账单
+
+美团支持导出账单证明，系统以 **CSV** 或 **zip** 形式导入。
+
+## 如何获取
+
+1. 打开美团 App，进入 **我的 → 钱包 → 账单**。
+2. 点击右上角的「**下载账单**」（或「开具账单证明」）。
+3. 选择时间范围，导出为 **CSV** 格式；账单导出周期为 3 个月，更早的记录需分段多次导出。
+4. 导出的文件通常打包为 zip 并设置**解压密码**，密码在「申请记录」页查看。
+
+## 导入
+
+在[账单导入](/guide/transactions)页选择账单类型「美团」，上传 CSV 或 zip 文件。
+
+- 支持格式：`.csv`、`.zip`
+- 若为加密压缩包，解析时会提示输入解压密码。
+
+## 字段映射
+
+系统以「交易创建时间」定位表头，读取以下列：
+
+| 源字段（CSV 列） | 落库字段 | 处理说明 |
+|---|---|---|
+| 交易成功时间 | `transaction_time` | 缺失时回退交易创建时间 |
+| 交易创建时间 | `transaction_time` | 仅作兜底 |
+| 订单标题 | `remark` | 作为备注 |
+| 交易单号 | `external_no` | 导入去重键（去除空白） |
+| 收/支 | `type` | 支出→EXPENSE，收入→INCOME |
+| 实付金额 | `amount` | 缺失时回退订单金额 |
+| 交易类型 | 仅推断/预览 | 不落库 |
+| — | `channel` | 固定为 `MEITUAN` |
+| — | `category_id` | 取导入面板默认分类；未选为 NULL |
+
+## 注意事项
+
+- 美团导出的压缩包一般有密码，请先记录「申请记录」页提供的解压密码。
+- 若提示密码错误，请核对密码后重新输入。

guide/bills/overview.md

@@ -0,0 +1,69 @@
+# 账单类型与获取
+
+系统当前支持 **7 类账单**的导入。不同平台导出的文件格式不同，导入时需要选择对应的账单类型。
+
+## 支持一览
+
+| 账单类型 | 应用 | 支持格式 | 典型文件名 |
+|---|---|---|---|
+| 支付宝 | 支付宝 App | CSV、zip | `alipay_record_YYYYMMDD_HHMM.zip` |
+| 微信 | 微信 App | xlsx、zip | `微信支付账单流水文件(起-止)_*.xlsx` |
+| 美团 | 美团 App | CSV、zip | `美团账单(起-止).csv` |
+| 淘宝 | 淘宝网页版 | xlsx | `订单数据.xlsx` |
+| 京东 | 京东 App | CSV、zip | `京东交易流水(*).csv` |
+| 招商银行 | 招商银行 App | CSV、PDF、zip | `CMB_*.csv` / `招商银行交易流水(*).pdf` |
+| 交通银行 | 交通银行 App | xls、zip | `交易明细列表.xls` |
+
+## 导出入口速查
+
+| 账单类型 | 导出路径 |
+|---|---|
+| 支付宝 | App → 我的 → 账单 → 右上角「…」→ 开具交易流水证明（最长 1 年，邮箱接收） |
+| 微信 | App → 我 → 服务 → 钱包 → 账单 → 常见问题 → 下载账单 → 用于个人对账（单次最长 3 个月，xlsx） |
+| 美团 | App → 我的 → 钱包 → 账单 → 右上角「下载账单」（导出周期 3 个月，CSV，需解压密码） |
+| 淘宝 | 网页版 → 我的淘宝 → 我的订单 → 已买到的宝贝 → 导出订单，下载 xlsx |
+| 京东 | App → 我的 → 设置 → 账单 → 右上角「…」→ 账单导出（设置接收邮箱），邮件接收 CSV |
+| 招商银行 | App 首页搜「流水打印」（PDF）；或个人网银专业版导出 Excel（近 13 个月） |
+| 交通银行 | App → 我的账户 → 明细清单 → 发送至邮箱（Excel，最长 1 年） |
+
+### 各渠道时间范围与格式对比
+
+| 渠道 | 可导出时间范围 | 常见格式 | 备注 |
+|---|---|---|---|
+| 支付宝 | 最长 1 年（可自定义，跨年分次） | CSV | 需支付密码验证，邮箱接收 |
+| 微信 | 单次最长 3 个月 | xlsx | 解压密码在微信支付公众号 |
+| 美团 | 单次 3 个月 | CSV | 解压密码在申请记录页 |
+| 淘宝 | 由订单导出页面限定 | xlsx | 订单级导出，多商品订单会合并展示 |
+| 京东 | 由账单导出页面限定 | CSV | 邮箱接收，通常打包为加密 zip，解压密码见邮件说明 |
+| 招商银行 App | 最长近 5 年（单次≤1 年） | PDF（带电子印章） | 解压密码在申请记录页 |
+| 招商银行 PC 专业版 | 近 13 个月 | xls / xlsx | 纯数据表格，无印章；xls 需转 CSV 后导入 |
+| 交通银行 App | 最长 1 年 | xls | 邮箱接收电子版 |
+
+::: tip 以 App 实际界面为准
+各平台导出入口可能随 App 版本调整，上述路径为常见版本；如界面有差异，可在对应 App 的帮助中心搜索「账单导出」。
+:::
+
+## 导出与导入建议
+
+1. **按时间范围分批导出**：多数平台单次导出有跨度或条数限制，可按年或按季度导出多个文件，逐个导入。
+2. **记录解压密码**：部分平台（如美团、部分银行）导出的压缩包设有密码，导入时需要输入。
+3. **优先选择系统直接支持的格式**：如招商银行 CSV 与 PDF 都支持，CSV 更易解析；银行账单如同时提供，优先 CSV。
+4. **注意去重**：系统按「用户 + 交易号」去重。同一账单重复导入时，已存在的记录会被自动跳过；银行账单没有交易号时会以「日期+类型+金额+余额」生成稳定的去重键。
+5. **按来源设置计入统计**：避免同一笔消费被重复统计。
+   - 来自**微信、支付宝**的账单：默认**计入统计**（除非有特殊情况）。
+   - 来自**其他**（银行、美团、淘宝、京东等）的账单：默认**不计入统计**——这些渠道的扣款往往最终走微信/支付宝支付，若都计入会导致统计翻倍。
+   - **例外**：工资、奖金等明确收入应计入统计。
+
+## 各账单详解
+
+- [支付宝账单](/guide/bills/alipay)
+- [微信支付账单](/guide/bills/wechat)
+- [美团账单](/guide/bills/meituan)
+- [淘宝账单](/guide/bills/taobao)
+- [京东账单](/guide/bills/jd)
+- [招商银行账单](/guide/bills/cmb)
+- [交通银行账单](/guide/bills/bocom)
+
+## 导入操作
+
+导出文件后，在「收支记录 → 导入账单」或通知邮件直达的独立页 `/bill-import` 中导入，流程见[收支记录 · 账单导入](/guide/transactions#账单导入)。

guide/bills/taobao.md

@@ -0,0 +1,43 @@
+# 淘宝账单
+
+淘宝支持导出「订单数据」，系统以 **xlsx** 形式导入。
+
+## 如何获取
+
+1. 打开**淘宝网页版**（电脑浏览器），登录后进入 **我的淘宝 → 我的订单 → 已买到的宝贝**。
+2. 点击「**导出订单**」，选择需要导出的时间范围。
+3. 导出为 **xlsx** 文件（通常命名为 `订单数据.xlsx`），按页面提示下载。
+
+::: tip 以实际界面为准
+淘宝导出入口可能随网页版本调整，如界面有差异，可在淘宝帮助中心搜索「导出订单」。
+:::
+
+## 导入
+
+在[账单导入](/guide/transactions)页选择账单类型「淘宝」，上传 xlsx 文件。
+
+- 支持格式：`.xlsx`
+- 淘宝订单均为购买支出，导入时固定记为支出（`EXPENSE`）。
+
+## 字段映射
+
+系统以「订单号」定位表头，读取以下列：
+
+| 源字段（xlsx 列） | 落库字段 | 处理说明 |
+|---|---|---|
+| 订单号 | `external_no` | 导入去重键；多商品订单共用同一订单号 |
+| 订单提交时间 | `transaction_time` | 兼容文本时间与 Excel 日期序列号 |
+| 店铺名称 | `remark` | 与商品名称拼接为备注 |
+| 商品名称 | `remark` | 多商品订单以「、」拼接 |
+| 实付金额 | `amount` | 订单级合计；为空时回退「Σ(商品金额×数量)+运费」 |
+| 订单状态 | 仅推断/预览 | 「交易关闭」标记为不可导入 |
+| — | `type` | 固定为 `EXPENSE`（支出） |
+| — | `channel` | 固定为 `TAOBAO` |
+| — | `category_id` | 取导入面板默认分类；未选为 NULL |
+
+## 注意事项
+
+- **多商品订单会合并为一条**：淘宝订单数据中，一个订单包含多个商品时会占用多行（订单级列以合并单元格展示），系统按订单号聚合，每个订单只生成一条记录。
+- **交易关闭不导入**：订单状态为「交易关闭」的记录标记为不可导入，默认不勾选。
+- **未完成订单**：如「卖家已发货」且实付金额为 0 的订单，因金额无效标记为不可导入，待订单完成后重新导出即可。
+- **去重**：系统按「用户 + 订单号」去重，重复导入同一订单会被自动跳过。

guide/bills/wechat.md

@@ -0,0 +1,49 @@
+# 微信支付账单
+
+微信支持导出「微信支付账单流水文件」，系统以 **xlsx** 或 **zip** 形式导入。
+
+## 如何获取
+
+1. 打开微信 App，进入 **我 → 服务 → 钱包 → 账单**。
+2. 点击右上角「常见问题」。
+3. 选择「下载账单」→ 用途选择「**用于个人对账**」。
+4. 选择交易类型（建议「全部交易」）与时间范围，输入接收邮箱，按提示输入支付密码完成验证。
+5. 账单会以**加密压缩包**形式发送到邮箱，解压密码在**微信支付公众号（服务通知）**中查看。
+
+要点：
+
+- 个人对账账单**单次最长可导出 3 个月**，更早的记录需分段多次导出。
+- 导出的账单**包含已删除的交易记录**。
+- 账单一般在几分钟内到达邮箱，最慢 24 小时内；未收到时请检查垃圾邮件。
+- 解压密码每次导出单独生成，微信登录密码、支付密码均不能用于解压。
+
+## 导入
+
+在[账单导入](/guide/transactions)页选择账单类型「微信」，上传 xlsx 或 zip 文件。
+
+- 支持格式：`.xlsx`、`.zip`
+- 系统按「交易单号」去重。
+
+## 字段映射
+
+系统以首列「交易时间」定位表头，读取以下列：
+
+| 源字段（xlsx 列） | 落库字段 | 处理说明 |
+|---|---|---|
+| 交易时间 | `transaction_time` | 兼容 Excel 日期序列号与文本时间 |
+| 交易对方 | `remark` | 与商品名称拼接为备注 |
+| 商品 | `remark` | 同上 |
+| 收/支 | `type` | 支出→EXPENSE，收入→INCOME |
+| 金额(元) | `amount` | 去千分位后解析 |
+| 交易状态 | 仅推断/预览 | 不落库 |
+| 交易单号 | `external_no` | 导入去重键 |
+| — | `channel` | 固定为 `WECHAT` |
+| — | `category_id` | 取导入面板默认分类；未选为 NULL |
+
+「/」等占位符会被视为空值。
+
+## 注意事项
+
+- 「用于个人对账」导出的 xlsx 为对账用途，字段完整，适合导入。
+- 微信账单导出通常有一定延迟（通过邮件下发），收到文件后再导入。
+- 「/」等占位符会被视为空值。