rosercode/ledgerly-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: 初始化文档站仓库

Browse Source
This commit is contained in:
rosercode
2026-09-21 13:38:20 +08:00
commit a4ae7ac979
58 changed files with 4622 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
guide/ai.md
+95
View File
@@ -0,0 +1,95 @@
# AI 能力
系统集成 **DeepSeek** 大模型，在分类打标、查询、记账等环节提供智能辅助。所有 AI 功能需先在「系统设置 → AI 模型配置」中启用并配置 API Key。
## 数据与隐私
系统仅向大模型发送完成功能所需的**最小字段**，**不会上传任何敏感数据**。所有 AI 请求均由你自行配置的接口地址发起。
**不会发送**：
- 账单导入的原始数据（`rawData`，可能含交易对方、商品名、订单号、对方账户/卡号等）；
- 金额；
- 交易号、账户/卡号、姓名、地址、电话等可识别个人或账户的信息。
**实际发送**（按功能所需最小化）：
- 分类/标签建议：记录的收支类型、备注、交易渠道；
- 智能查询 / 统计：你输入的自然语言，以及分类与标签名称；
- 智能记账：你输入的一句话；
- 生成分类/标签、推荐 Emoji/颜色：你输入的名称或描述；
- 生成规则：所选记录的类型、备注、交易渠道、已有分类与标签（不含金额与原始账单数据）。
API Key 仅保存在本地数据库中，仅用于向你配置的接口地址发起请求，不会随上述数据一并外发。
## 配置
在「系统设置 → AI 模型配置」中：
- 开启「启用 AI 建议」。
- 填写 **API Key**。
- 可选修改 **接口地址**（默认 `https://api.deepseek.com`）与**模型**（默认 `deepseek-chat`）。
- 点击「测试连接」验证配置。
![系统设置](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/settings.png)
## 功能一览
| 功能 | 入口 | 说明 |
|---|---|---|
| 分类/标签建议 | 收支记录 → 一键设置 → AI 智能建议 | 对当前页记录批量建议分类与标签，可一键采纳 |
| 单条建议 | 新增/编辑记录 → AI 推荐 | 推荐已有分类或标签 |
| 智能查询 | 收支记录 → AI 智能查询 | 自然语言解析为筛选条件 |
| 智能记账 | 收支记录 → 智能记账 | 一句话解析为一笔记录 |
| 生成分类 | 分类管理 → AI 生成 | 由用途描述生成分类 |
| 推荐 Emoji | 分类管理 → AI 推荐 | 为分类推荐 Emoji 图标 |
| 推荐颜色 | 标签管理 → AI 推荐 | 为标签推荐颜色 |
| 生成规则 | 规则管理 → AI 生成规则 | 由已打标签的记录归纳分类与标签规则 |
| 统计搜索 | 统计面板 → AI 搜索 | 自然语言解析为统计筛选条件与维度 |
## 分类与标签建议
在收支记录页点「一键设置」，选择建议范围（分类与标签 / 仅分类 / 仅标签）后点「AI 智能建议」。系统会按记录的类型、备注、交易渠道等聚合后请求模型，返回建议并进入 AI 建议弹窗。
弹窗中每条记录展示建议分类、建议标签与理由，默认全选。若建议了系统中不存在的分类或标签，会以「新建」标记，确认后自动创建。应用时分类会被覆盖、标签会被追加。
## 智能查询
在收支记录页的 AI 查询框中输入自然语言，例如：
- 「上个月餐饮」→ 时间范围 + 分类
- 「超过500的支出」→ 类型 + 金额区间
- 「待报销的支出」→ 标签 + 类型
- 「微信支付」→ 交易渠道
解析结果会直接应用为筛选条件并立即查询。
## 智能记账
在「智能记账」弹窗中描述一笔收支，AI 解析出类型、金额、分类、交易渠道、时间、备注、标签等字段，并预填到新增记录表单，确认后保存。
![AI 智能记账弹窗](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/ai-record.png)
## AI 统计搜索
在统计面板顶部的 AI 搜索框中用一句自然语言描述统计意图，例如「上个月餐饮花了多少」「近半年交通支出趋势，按周看」。系统会解析为**时间范围、收支类型、分类、标签、交易渠道、金额区间、备注、统计口径与趋势粒度**并自动回填、刷新图表。详见[统计面板](/guide/dashboard)。
## AI 生成规则
在规则管理页点「AI 生成规则」，选择用于归纳的**已打标签记录**（默认全选当前页，支持搜索、筛选与分页），AI 会依据这些记录的**类型、备注、交易渠道、已有分类与标签**生成规则建议，预览编辑后批量创建。与已有规则重复的建议会标记「已存在」并禁止导入。详见[规则管理](/guide/rules)。
## 用量统计
「模型使用情况」页面（系统设置 → AI 模型配置 →「使用情况」）展示 AI 调用汇总与明细。
![模型使用情况](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/ai-usage.png)
- **调用概览**：调用次数、成功、失败、总 Token。
- **Token 明细**：输入 Token、输出 Token、缓存命中。
- **最近调用记录**：时间、类型、分析条数、Token、耗时、状态。
## 说明
- AI 建议结果仅供参考，应用前可逐条取消勾选。
- 关闭「启用 AI 建议」后，系统不会发起任何 AI 请求，相关入口也会隐藏。
- 账单类型识别（邮箱账单）使用的是**发件人规则**而非 AI，结果更确定、可预期。
guide/bills/alipay.md
+63
View File
@@ -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
+51
View File
@@ -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
+81
View File
@@ -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
+47
View File
@@ -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
+38
View File
@@ -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
+69
View File
@@ -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
+43
View File
@@ -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
+49
View File
@@ -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 为对账用途，字段完整，适合导入。
- 微信账单导出通常有一定延迟（通过邮件下发），收到文件后再导入。
- 「/」等占位符会被视为空值。
guide/categories-tags.md
+55
View File
@@ -0,0 +1,55 @@
# 分类与标签
分类用于区分收支的**用途**（如餐饮、交通、工资），标签用于给记录附加**自定义维度**（如报销、旅行、大额消费）。两者都可自定义。
## 分类管理
![分类管理](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/categories.png)
页面分为「支出分类」与「收入分类」两张表格，展示名称（含 Emoji 图标）、图标、排序与操作。
### 新增分类
1. 在分类管理页右上角点击「**新增分类**」。
2. 在弹窗中填写：
- **分类名称**
- **类型**：支出 / 收入
- **图标**：点击选择 Emoji（启用 AI 后可点「AI 推荐」）
- **排序**：数字越小越靠前
3. 点击「确定」保存。
![新增分类弹窗](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/add-category.png)
> 启用 AI 后，还可在弹窗顶部输入用途描述，点「AI 生成」自动填充名称、类型与图标。
### 编辑与删除
- **编辑**：在分类行点击「编辑」修改。
- **删除**：点击「删除」并确认；已使用该分类的记录会变为「未分类」。
- **图标**：使用 Emoji 选择器挑选，也可自定义输入。
- **AI 生成分类**：启用 AI 后，输入用途描述（如「日常通勤打车地铁」），点「AI 生成」自动填充名称、类型与图标。
新注册用户会自动获得一套默认分类（如餐饮、交通、购物、居住、通讯、娱乐、医疗、教育等）。
## 标签管理
![标签管理](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/tags.png)
### 新增标签
1. 在标签管理页右上角点击「**新增标签**」。
2. 填写标签名称、颜色与排序（启用 AI 后可点「AI 推荐」自动配色）。
3. 点击「确定」保存。
![新增标签弹窗](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/add-tag.png)
- **颜色**：使用颜色选择器，内置常用色板；启用 AI 后点「AI 推荐」可按标签名称推荐颜色。
- 标签以彩色标签形式在收支记录、导入预览等位置展示。
- 删除标签会从所有交易记录中移除该标签，操作前会二次确认。
## 使用建议
- 分类尽量保持精简、稳定，便于统计对比；细粒度维度用标签补充。
- 建议为以下场景建立标签：报销/待报销、旅行、大额消费、订阅、礼物、家庭、工作等。
- 需要按规则自动归类时，配合[规则管理](/guide/rules)使用：规则命中后会自动应用分类与标签。
- 分类与标签都支持在[账单导入](/guide/transactions)预览阶段批量指定为默认值。
guide/dashboard.md
+82
View File
@@ -0,0 +1,82 @@
# 统计面板
「统计面板」是登录后的默认首页，用于查看指定时间范围内的收支汇总与图表。
![统计面板](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/dashboard.png)
## 时间范围
顶部下拉可选择统计的时间范围：
| 选项 | 含义 |
|---|---|
| 本月 | 当月 1 日 00:00:00 ~ 当月最后一天 23:59:59（默认） |
| 近3月 | 含本月在内向前共 3 个月 |
| 近12月 | 含本月在内向前共 12 个月 |
| 自定义 | 手动选择起止日期（结束日按 23:59:59 计算） |
右侧实时显示当前查询区间。
## 时间粒度
趋势图右上角可选择粒度：**按日 / 按周 / 按月 / 按季 / 按年**。切换时间范围时会给出默认粒度（近12月→按月，近3月→按周，本月→按日）。区间内没有数据的点会补 0，保证趋势连续。
## AI 搜索
启用 AI 后，页面顶部会出现「**AI 搜索**」按钮，点击打开搜索弹窗。用一句自然语言描述统计意图，系统会调用大模型解析为统计参数并自动回填、刷新图表，例如：
- 「上个月餐饮花了多少」→ 时间范围 + 分类
- 「近半年交通支出趋势，按周看」→ 时间范围 + 分类 + 按周粒度
- 「今年各类支出占比」→ 时间范围 + 类型
![AI 统计搜索弹窗](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/ai-search.png)
可解析并回填的参数包括：**时间范围、收支类型、分类、标签、交易渠道、金额区间、备注、统计口径**与**趋势粒度**。弹窗内提供示例问题，输入框会记住历史记录（可一键清空）；回车或点击「AI 查询」即可执行，无可用条件时会提示且不改动当前筛选。详见 [AI 能力](/guide/ai)。
## 筛选条件
- **统计口径**：仅计入统计（默认）/ 全部记录 / 仅不计入。默认只统计「计入统计」的记录，建议按来源设置（微信/支付宝计入、其他来源不计入），避免多来源重复统计。
- **类型**：支出 / 收入（多选）。
- **分类**：多选，含「未分类」。
- **交易渠道**：多选。
- **标签**：多选。
- **金额区间**：最小 ~ 最大。
- **备注搜索**。
点击「重置筛选」可清空筛选（保留时间范围与粒度）。筛选条件会记住，下次进入自动还原。
## 汇总卡片
第一行展示四项汇总：**总收入**、**总支出**、**结余**、**交易笔数**。
第二行展示派生指标：**日均收入**、**日均支出**、**最大单笔支出**（附带备注摘要）、**平均每笔支出**。
## 图表
| 图表 | 说明 |
|---|---|
| 收支趋势（柱状图） | 按所选粒度展示收入（绿）与支出（红），点击柱子或该列空白处可跳转查看对应明细 |
| 支出分类占比（环形图） | 各分类支出金额占比 |
| 收入分类占比（环形图） | 各分类收入金额占比 |
| 支出交易渠道占比（环形图） | 仅统计支出，按交易渠道 |
| 收入交易渠道占比（环形图） | 仅统计收入，按交易渠道 |
切换语言时，图表标题、图例与交易渠道名称会实时重绘。
### 点击趋势图查看明细
「收支趋势」柱状图的**整列都可点击**：点中柱子，或点击柱子顶端上方的空白处均可。点击后跳转到[收支记录](/guide/transactions)，并自动带入该列对应的筛选条件：
- **类型**：点中柱子时取该柱子的收入 / 支出；点击空白处时不限定类型（沿用面板当前类型筛选）；
- **日期范围**：该列代表的时间桶——按日→当天、按周→周一至周日、按月→当月、按季→当季、按年→当年；
- **其他筛选**：统计面板当前的统计口径、分类、交易渠道、标签、金额区间与备注关键字。
![点击趋势柱状图跳转收支记录](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/dashboard-trend-jump.png)
跳转后可直接查看该时间段内的对应明细；筛选条件会照常记忆，收支记录页原有的每页条数与排序偏好不受影响。
## 小技巧
- 想知道「上个月餐饮花了多少」，可把时间范围设为「本月」或自定义，并在分类中只勾选「餐饮」。
- 不计入统计的记录（如借款、账户间转账）默认不会计入汇总；如需查看全部，把统计口径切换为「全部记录」。
- 想快速核对某月、某周或某天的明细，直接点击「收支趋势」上对应的列（柱子或该列空白处），即可带着时间范围跳到收支记录。
guide/email-bills.md
+84
View File
@@ -0,0 +1,84 @@
# 邮箱账单
邮箱账单功能通过 **IMAP** 监听邮箱，当账单邮件到达时自动拉取附件，识别账单类型并进入待处理列表，由你预览后再确认导入。
页面包含三个标签页：**邮箱配置**、**发件人规则**、**待处理账单**。
## 邮箱配置
![邮箱配置](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/email-bills-configs.png)
配置用于接收账单邮件的 IMAP 邮箱：
1. 点击右上角「**新增**」，填写邮箱信息：
- **名称**：便于识别的名称
- **IMAP 服务器**：可从内置列表选择或自定义（选择后自动填端口 993 并开启 SSL）
- **邮箱账号 / 授权码**：授权码在邮箱设置中开启 IMAP 服务后生成
- **监听文件夹**：默认 `INBOX`
- **默认归类**：默认支出/收入分类与标签
- **拉取范围**：仅新邮件 / 最近 N 天 / 最近 N 封
- **启用**：开启后持续监听
2. 点击「保存」。
![邮箱配置弹窗](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/add-email-config.png)
- **IMAP 服务器**：可从内置列表选择（QQ、腾讯企业邮、163、126、网易企业邮、阿里云、新浪、139、189、Gmail、Outlook、iCloud）或自定义，选择内置服务器会自动填端口 993 并开启 SSL。
- **邮箱账号 / 授权码**：授权码而非登录密码（在邮箱设置中开启 IMAP 服务后生成）。
- **监听文件夹**：默认 `INBOX`。
- **默认归类**：默认支出分类、收入分类与标签。
- **拉取范围**：仅新邮件（增量）/ 最近 N 天 / 最近 N 封。
- **启用**：开启后系统会持续监听该邮箱。
行操作：
- **测试连接**：验证 IMAP 配置。
- **立即检查**：实时展示检查进度，完成后提示新增待处理账单数量。
- **编辑 / 删除**。
## 发件人规则
![发件人规则](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/email-bills-sender-rules.png)
根据邮件**发件人**识别账单类型与解析参数：
- **发件人匹配串**：每行一个，支持完整地址、`@域名` 或关键字，包含匹配且忽略大小写。
- **账单类型**：支付宝 / 微信 / 美团 / 淘宝 / 京东 / 招商银行 / 交通银行。
- **解压密码**：账单压缩包加密时填写。
- **默认归类**：默认支出分类、收入分类与标签。
- **优先级**：值越小越优先。
系统为常见账单邮箱预置了默认规则（如支付宝 `@alipay.com`、微信 `@wechatpay.com`、美团 `@meituan.com`、招行 `@message.cmbchina.com`、交行 `@bankcomm.com`）。
## 待处理账单
![待处理账单](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/email-bills-messages.png)
展示已拉取、待处理的邮件账单，可按状态筛选（待解析 / 已导入 / 已忽略），列表每 30 秒自动刷新。
行操作：
- **解析**：选择账单类型与解压密码后解析，进入预览，确认后导入。
- **忽略**：标记为已忽略，不再处理。
- **删除**：删除该消息及本地附件。
## 工作流程
```text
账单邮件到达
│
▼
IMAP 监听（IDLE 实时 / 轮询降级）
│ 提取附件并保存
▼
发件人规则匹配 → 确定账单类型、解压密码、默认归类
│
▼
进入「待处理账单」（状态：待解析）
│ 手动点「解析」→ 预览 → 确认导入
▼
写入收支记录（状态：已导入）
```
::: tip 先预览再导入
邮箱账单不会自动写入账本，必须经过预览确认，避免误导入。
:::
guide/faq.md
+94
View File
@@ -0,0 +1,94 @@
# 常见问题
## 安装与启动
### 没有数据库能启动吗？
可以。系统支持启动后再配置数据库：未配置时前端会引导进入「初始化数据库」页面，选择 SQLite（零配置）或 MySQL 并保存后即可使用。
### 前端打包后刷新子路由 404？
使用 `bootJar` 打包的一体化 jar 已内置 SPA 路由回退：访问 `/dashboard` 等子路径会由后端回退到 `index.html`。若自行用 Nginx 托管前端产物，需配置 history 模式回退。
## 账单导入
### 支持哪些账单？
支付宝、微信、美团、招商银行、交通银行，详见[账单类型与获取](/guide/bills/overview)。
### 导入后重复了怎么办？
系统按「用户 + 交易号」去重，重复导入同一账单时已存在的记录会被跳过。若已产生重复，可在[收支记录](/guide/transactions)中勾选后批量删除。
### 提示需要解压密码？
部分平台（如美团、部分银行）导出的账单压缩包设有密码。请到导出时的「申请记录」或相应页面查看密码，在解析弹窗中输入。
### 为什么有些行不能导入？
常见原因：金额或时间字段无法解析、该交易号已存在、或银行 PDF 的余额连续性校验未通过。预览页会显示具体状态。
### 银行账单没有交易号，会重复吗？
不会。银行流水会以「日期 + 类型 + 金额 + 余额」生成稳定去重键；招商银行 CSV 与 PDF 生成规则一致，可混用。
## 统计与记录
### 借款、转账会计入统计吗？
默认计入。建议在记录或导入时将「计入统计」关闭，这类记录会从统计中排除，但仍保留在列表中。
### 多来源账单如何避免重复统计？
同一笔消费可能同时出现在多个账单中（例如通过微信付款、实际由招商银行卡扣款），若都计入统计会重复。推荐按来源设置「计入统计」：
- **微信、支付宝**来源：默认**计入**（除非有特殊情况）。
- **其他**来源（银行、美团、淘宝、京东等）：默认**不计入**——这些渠道的扣款往往最终走微信/支付宝支付。
- **例外**：工资、奖金等明确收入应计入。
可在[账单导入](/guide/transactions)预览页用「设为计入 / 设为不计入」批量设置，或在[收支记录](/guide/transactions)中逐条切换。
### 想让备注不显示在界面上？
可在记录行使用「隐藏」功能，备注会显示为 `******`，需要时再「查看」或「取消隐藏」。
### 分类和标签有什么区别？
分类用于区分收支用途（餐饮、交通、工资），是统计的主要维度；标签用于附加自定义维度（报销、旅行、大额消费），一笔记录可有多个标签。
## AI 与通知
### AI 功能不可用？
请先在「系统设置 → AI 模型配置」中开启并填写 API Key，然后点「测试连接」验证。
### 邮箱账单会自动入库吗？
不会。邮箱账单拉取后进入「待处理账单」，需要手动解析、预览并确认后才写入账本。
### 账单类型识别用 AI 吗？
不使用。邮箱账单的类型由**发件人规则**确定，结果确定、可预期；识别不出的可在解析时手动选择类型。
### 到点没有收到提醒？
检查：提醒是否启用、是否配置了启用的渠道、提醒时间是否为 `HH:mm` 格式。可先点「立即发送」验证渠道配置，并查看发送日志。
## 账号与数据
### 忘记密码怎么办？
当前版本未提供自助找回。可在数据库中重置对应用户的密码哈希，或新建账号后迁移数据。
### 数据存在哪里？
- SQLite：默认位于服务运行目录的 `data/` 下，配置文件为 `config/database.json`。
- MySQL：位于所配置的数据库中。
### 切换数据库会迁移数据吗？
不会。切换后原数据库数据保留，需要自行迁移。
### 支持哪些界面语言？
简体中文、English、日本語，可在登录页或主界面顶部切换。
guide/getting-started.md
+65
View File
@@ -0,0 +1,65 @@
# 快速开始
本章面向**已部署好的系统**，介绍初次使用时需要完成的配置与操作。
> 如何安装、启动与部署（开发模式、打包可执行 jar、Docker），请见开发文档的[构建与部署](/dev/build-deploy)。
## 访问系统
使用部署者提供的地址访问，例如：
- 本机部署：`http://localhost:8080`（端口以实际部署为准）
- 局域网 / 服务器：`http://<服务器 IP>:<端口>`
### 在线体验
不想自行部署？可直接访问在线演示环境：
- 地址：[https://finance.rosercode.cn/](https://finance.rosercode.cn/)
- 演示账号：`demo` / `demo123456`
> 在线环境使用独立的 SQLite 演示库与虚构数据，仅供功能体验，请勿录入真实账目。
首次访问且数据库尚未配置时，会自动进入「初始化数据库」引导页。
## 数据库配置
系统支持在服务启动**之后**再配置数据库，无需启动前准备：
- 未检测到配置时，应用仍可正常启动，前端会引导进入「初始化数据库」页面。
- 支持 **SQLite**（本地单文件，零配置）与 **MySQL** 两种数据库。
- 保存配置后立即生效并自动建表，无需手动执行 SQL。
- 配置持久化在 `config/database.json`，SQLite 数据默认位于 `data/` 目录。
![数据库初始化](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/settings.png)
首次进入时按引导选择数据库类型并填写连接信息，点击「保存并应用」即可。登录后可通过右上角用户菜单 →「数据库设置」随时切换数据库；切换后原数据库的数据保留，不做自动迁移。
## 注册与登录
- 首次使用需要注册账号。若系统尚无任何用户，注册入口始终可用。
- 注册成功后使用用户名与密码登录，登录状态通过 JWT 保存。
![登录卡片](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/login-card.png)
![注册卡片](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/register-card.png)
注册功能可在「系统设置 → 注册设置」中开启或关闭。新注册用户会自动获得一套默认分类、标签与邮箱发件人规则。
## 界面语言
系统支持**简体中文、English、日本語**三种语言。登录页、注册页右上角以及主界面顶部栏均可切换语言。
## 首次使用建议
1. 完成数据库配置并注册登录。
2. 进入「分类管理」「标签管理」按自己的习惯调整分类与标签。
3. 在「规则管理」配置常用自动归类规则（如「星巴克 → 餐饮」）。
4. 导出并导入历史账单（见[账单类型与获取](/guide/bills/overview)）。
5. 按需配置「AI 模型」「定时通知」「邮箱账单」。
## 下一步
- [统计面板](/guide/dashboard)
- [收支记录](/guide/transactions)
- [账单导入](/guide/transactions)
guide/index.md
+37
View File
@@ -0,0 +1,37 @@
# 使用文档
本章面向**使用者**，介绍系统的安装启动、各功能的使用方法与各类账单的获取方式。
## 开始使用
- [项目简介](/guide/introduction)：系统定位、核心功能与技术栈
- [快速开始](/guide/getting-started)：数据库配置、注册登录、界面语言与首次使用建议
- [统计面板](/guide/dashboard)：时间范围、筛选条件与图表说明
## 记账与整理
- [收支记录](/guide/transactions)：记录管理、筛选、批量操作、账单导入、AI 建议与记账
- [分类与标签](/guide/categories-tags)：分类与标签的维护与使用建议
- [规则管理](/guide/rules)：按关键词/金额/类型自动归类打标，支持 AI 生成规则、搜索与分页
- [邮箱账单](/guide/email-bills)：IMAP 自动拉取账单邮件
## 智能与自动化
- [AI 能力](/guide/ai)：分类标签建议、自然语言查询与记账、AI 搜索与规则生成、用量统计
- [定时提醒与通知](/guide/notifications)：多渠道账单导入提醒
## 系统
- [系统设置](/guide/settings)：数据库、注册、账单来源统计、外观、AI、通知配置
- [系统日志](/guide/logs)：访问日志、登录日志、运行日志
## 账单获取
- [账单类型总览](/guide/bills/overview)
- [支付宝账单](/guide/bills/alipay) / [微信支付账单](/guide/bills/wechat) / [美团账单](/guide/bills/meituan) / [淘宝账单](/guide/bills/taobao) / [京东账单](/guide/bills/jd) / [招商银行账单](/guide/bills/cmb) / [交通银行账单](/guide/bills/bocom)
## 其他
- [常见问题](/guide/faq)
> 想了解系统内部设计与二次开发？请查看[开发文档](/dev/)。
guide/introduction.md
+55
View File
@@ -0,0 +1,55 @@
# 项目简介
收支管理系统是一个**自托管的个人收支管理应用**，用于把分散在支付宝、微信、美团、银行等平台的账单汇总到一处，统一分类、打标签、统计收支，并通过自定义规则与 AI 能力减少手工整理的工作量。
## 解决什么问题
日常消费分散在多个平台：扫码用微信/支付宝、外卖在美团、大额消费走银行卡。各平台账单格式不同、导出入口不同，手动记录既繁琐又容易遗漏。本系统提供：
- **多来源账单导入**：支付宝（CSV）、微信（xlsx）、美团（CSV）、淘宝（xlsx）、京东（CSV）、招商银行（CSV/PDF）、交通银行（xls），支持加密 zip 压缩包；解析预览后再确认导入，按交易号去重。
- **自动归类**：自定义规则按关键词、收支类型、金额区间自动匹配分类与标签；AI 可对已有记录批量给出分类/标签建议。
- **统计与图表**：月度汇总、分类占比、收支趋势、交易渠道占比，支持自定义时间范围与多维度筛选。
- **自动化提醒**：按周期提醒导入新账单；也可通过 IMAP 监听邮箱自动拉取账单邮件。
## 核心功能
| 模块 | 能力 |
|---|---|
| 收支记录 | 增删改查、分页与多条件筛选、批量设置分类/标签、批量删除、计入统计开关、备注隐藏、导出 Excel |
| 分类与标签 | 收入/支出分类与标签的增删改查，新用户自动获得默认数据，AI 推荐 Emoji 与颜色 |
| 统计图表 | 月度收支、分类占比、收支趋势、交易渠道占比，支持按日/周/月/季/年粒度，点击趋势图可下钻对应明细 |
| 账单导入 | 七类账单解析、zip 解密、解析预览、按交易号去重、规则建议 |
| 自定义规则 | 关键词/收支类型/金额区间组合，优先级排序、启用停用，导入时自动应用；支持 AI 生成规则、搜索与分页 |
| AI 能力 | 分类标签建议、自然语言查询、自然语言记账、AI 统计搜索、AI 生成规则、分类/标签生成、Emoji/颜色推荐、用量统计 |
| 邮箱账单 | 多邮箱 IMAP IDLE 监听、发件人规则识别账单类型、待处理列表先预览再导入 |
| 定时通知 | 每天/每周/每月提醒，邮箱 SMTP 与 Server 酱渠道，发送日志 |
| 系统日志 | 访问日志、登录日志、运行日志在线查看，运行日志实时推送，自动清理 |
| 账号与多语言 | JWT 登录、注册开关、运行时数据库配置（SQLite/MySQL）、中/英/日三语 |
## 技术栈
| 层级 | 技术 |
|---|---|
| 后端 | Spring Boot 3.3.6 + Java 21 + MyBatis-Plus 3.5.12 + MySQL / SQLite |
| 前端 | Vue 3 + TypeScript + Vite + Naive UI + ECharts + Pinia |
| 构建 | Gradle 8.13（后端）/ npm（前端） |
| 认证 | JWT |
| 对象映射 | MapStruct 1.6.3 |
| 账单解析 | EasyExcel 4.0.3 + PDFBox 3.0.3 + Zip4j 2.11.5 |
| AI 能力 | DeepSeek |
| 通知渠道 | 邮箱 SMTP / Server 酱 |
| 多语言 | 中文 / 英文 / 日文（vue-i18n） |
| API 文档 | Knife4j（OpenAPI 3） |
## 适用场景
- 个人或家庭希望把多平台账单集中管理、统一统计。
- 希望按自己的习惯自定义分类、标签与自动归类规则。
- 希望借助 AI 快速完成分类打标、自然语言查询与记账。
- 希望私有部署，数据保存在本地 SQLite 或自有 MySQL 中。
## 下一步
- [快速开始](/guide/getting-started)：初次使用与配置
- [账单类型与获取](/guide/bills/overview)：了解支持哪些账单、如何导出
- [整体架构](/dev/architecture)：了解内部设计
guide/logs.md
+40
View File
@@ -0,0 +1,40 @@
# 系统日志
系统日志通过右上角用户菜单 →「系统日志」进入，包含三个标签页：**访问日志**、**登录日志**、**运行日志**。页头右上角可选择日志保留时长（30 天 / 90 天 / 180 天 / 永久保留）。
## 访问日志
![访问日志](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/logs-http.png)
记录每一次接口访问：
- 筛选：关键字（路径/参数/IP）、请求方法、状态码。
- 表格列：时间、方法、路径、参数、状态码、耗时、用户、IP。
- 支持分页与刷新。
## 登录日志
![登录日志](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/logs-login.png)
记录每次登录尝试（成功与失败）：
- 筛选：关键字（用户名等）、结果（成功/失败）。
- 表格列：时间、用户名、结果、说明、IP、User-Agent。
## 运行日志
![运行日志](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/logs-app.png)
在线查看后端运行日志：
- 筛选：日期、时间范围（最近 1/6/24 小时或全部）、级别（ERROR/WARN/INFO/DEBUG）、关键字、行数。
- 开启「实时」后通过 SSE 订阅新增日志，先回放最近内容再增量推送。
- 页面显示当前日志文件名与命中行数。
## 日志清理
访问日志与登录日志会按配置的保留天数自动清理（默认 30 天，设为永久保留则不清理），无需手动维护。
::: tip 排查问题
接口报错时，可先在「访问日志」定位失败请求（状态码 4xx/5xx），再到「运行日志」按时间与关键字查看异常堆栈。
:::
guide/notifications.md
+37
View File
@@ -0,0 +1,37 @@
# 定时提醒与通知
系统可按周期提醒你导入新账单，并通过邮箱或 Server 酱推送通知。配置入口为「系统设置 → 定时通知」。
![系统设置](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/settings.png)
## 提醒周期
- **通知链接地址**：通知正文中附带的跳转链接（如指向账单导入页 `/bill-import`）。
- **启用定时提醒**：开启后按周期发送。
- **提醒周期**：每天 / 每周（选择星期几）/ 每月（选择 1–28 日，默认每月 1 日）。
- **提醒时间**：`HH:mm` 格式（如 `09:00`）。
## 推送渠道
点击「添加渠道」新增，支持两种类型：
| 渠道 | 配置项 |
|---|---|
| Server 酱 | SendKey（在 sct.ftqq.com 获取），可推送到个人微信 |
| 邮箱 | SMTP 服务器、端口、邮箱账号、授权码、收件人、是否使用 SSL |
![添加渠道弹窗](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/add-channel.png)
每个渠道可单独「测试」「编辑」「删除」，并可通过启用开关控制是否参与发送。
面板右上角的「立即发送」可向所有启用渠道立即发送一次提醒，用于验证配置。
## 发送日志
「定时通知」面板下方展示最近发送记录（最多 20 条），包含成功/失败、时间、渠道类型与说明，便于排查问题。
## 说明
- 首次启用提醒时，系统会将「上次发送时间」置为当前，避免启用后立即补发历史提醒。
- 提醒正文默认提示导入新账单，并附带配置的通知链接地址。
- 若当前没有任何启用的渠道，到点时不会发送，待配置渠道后在本周期内仍可触发。
guide/pages.md
+55
View File
@@ -0,0 +1,55 @@
# 页面总览
本节汇总系统的全部页面、用途、入口方式与相互之间的跳转关系。
## 页面清单
| 页面 | 路由 | 用途 | 入口方式 |
|---|---|---|---|
| 登录 | `/login` | 用户名密码登录 | 未登录访问受保护页面时自动跳转 |
| 注册 | `/register` | 创建账号 | 登录页「没有账号？去注册」（注册开启时） |
| 数据库初始化 | `/database-setup` | 首次配置数据库 | 数据库未配置时自动引导 |
| 统计面板 | `/dashboard` | 收支汇总与图表 | 登录后默认页；左侧菜单 |
| 收支记录 | `/transactions` | 记录管理与**账单导入** | 左侧菜单 |
| 分类管理 | `/categories` | 收入/支出分类维护 | 左侧菜单 |
| 标签管理 | `/tags` | 标签维护 | 左侧菜单 |
| 规则管理 | `/rules` | 自动归类规则 | 左侧菜单 |
| 邮箱账单 | `/email-bills/*` | 邮箱配置 / 发件人规则 / 待处理账单 | 左侧菜单 |
| 系统设置 | `/settings` | 数据库 / 注册 / 账单来源统计 / 外观 / AI / 通知配置 | 顶部用户菜单 |
| 模型使用情况 | `/ai-usage` | AI 调用统计与明细 | 设置页「AI 模型配置」→ 使用情况 |
| 系统日志 | `/logs/*` | 访问 / 登录 / 运行日志 | 顶部用户菜单 |
| 账单导入（独立页） | `/bill-import` | 手机端上传账单 | **仅由通知邮件链接直达** |
## 全局导航
### 左侧菜单
统计面板 → 收支记录 → 分类管理 → 标签管理 → 规则管理 → 邮箱账单
### 顶部用户菜单
- **系统日志**：`/logs`
- **系统设置**：`/settings`
- **退出**：清空登录态并返回 `/login`
> 「模型使用情况」没有独立菜单入口，需从「系统设置 → AI 模型配置 → 使用情况」进入。
## 典型跳转路径
- **首次使用**：`/database-setup` → `/register` → `/login` → `/dashboard`
- **手动记账**：收支记录 → 点击「新增记录」→ 表单弹窗 → 保存
- **查看趋势明细**：统计面板 → 点击「收支趋势」某一列（柱子或该列空白处）→ 收支记录（自动带入时间范围、类型与当前筛选条件）
- **账单导入**：收支记录 → 点击「导入账单」→ 解析预览 → 确认导入 → 回到收支记录
- **手机导入**：通知邮件链接 → `/bill-import`（独立页，非弹窗）→ 上传解析 → 确认导入
- **自动归类**：规则管理配置规则 → 账单导入预览时命中并给出建议
- **邮箱账单**：邮箱配置 → 发件人规则 → 待处理账单 → 解析 → 导入到收支记录
- **AI 辅助**：系统设置启用 AI → 统计面板「AI 搜索」、收支记录「一键设置 / 智能记账 / AI 查询」、分类与标签「AI 推荐」、规则管理「AI 生成规则」
- **系统维护**：顶部菜单 → 系统设置 / 系统日志
## 页面关系说明
- **收支记录**是核心页面：手动记账、账单导入、批量设置、AI 能力都从这里进入，导入完成后也回到该页查看。
- **账单导入**有两条独立路径：
- 收支记录页的「导入账单」**弹窗**（桌面端常用）；
- 通知邮件直达的 **`/bill-import` 独立页**（面向手机，非弹窗，元素精简，系统内无其他入口）。
- **系统设置**聚合了数据库、注册、账单来源统计、外观、AI、通知六类配置；模型用量与日志分别从设置页与顶部菜单进入。
guide/rules.md
+85
View File
@@ -0,0 +1,85 @@
# 规则管理
规则用于**自动归类**：命中条件后自动应用指定的分类与标签，减少手动整理。
![规则管理](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/rules.png)
## 创建规则
1. 在规则管理页右上角点击「**新增规则**」。
2. 填写规则名称，并按需设置条件与结果：
| 字段 | 说明 |
|---|---|
| 类型 | 不限类型 / 支出 / 收入 |
| 关键词 | 匹配备注、交易对方、商品名称（包含即命中） |
| 金额区间 | 最小值 ~ 最大值（可只填一端） |
| 目标分类 | 命中后应用的分类 |
| 目标标签 | 命中后应用的标签（可多选） |
| 启用 / 排序 | 是否启用、优先级（越小越优先） |
3. 点击「确定」保存。
![新增规则弹窗](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/add-rule.png)
## 规则条件
一条规则可组合以下条件：
| 条件 | 说明 |
|---|---|
| 类型 | 不限类型 / 支出 / 收入 |
| 关键词 | 匹配备注、交易对方、商品名称，**包含即命中**（忽略大小写） |
| 金额区间 | 最小值 ~ 最大值（含边界，可只填一端） |
| 目标分类 | 命中后应用的分类（可不选） |
| 目标标签 | 命中后应用的标签（多选，可不选） |
| 优先级 | 排序值越小越优先 |
| 启用 | 可随时启用或停用 |
## 命中规则
- **分类**：取优先级最高（排序值最小）且与交易类型一致的命中规则。
- **标签**：取所有命中规则标签的并集。
- 规则在**账单导入的解析预览阶段**即会展示命中的规则名与建议分类/标签；确认导入时，**规则建议的分类优先于面板默认分类**，标签与默认标签合并去重。
## 搜索与分页
规则列表支持按条件检索与分页：
- **搜索**：按**规则名称或关键词**模糊匹配。
- **筛选**：**启用状态**（已启用 / 已停用）、**收支类型**（收入 / 支出）。
- **分页**：每页 10 / 20 / 50 / 100 条。
点击「搜索」按条件查询，「清空」重置全部条件。新增规则后回到第一页，便于查看新规则。
## AI 生成规则
启用 AI 后，规则管理页右上角会出现「**AI 生成规则**」按钮，可让 AI 依据**已打标签的记录**自动归纳出「关键词 → 分类/标签」规则，无需手工逐条编写。
流程为两步：
1. **选择记录**：列出当前用户**已打标签**的记录，默认全选当前页。可按**备注关键字**搜索，并按**收支类型、标签**筛选；支持分页与每页条数切换，可「全选本页」或「清空选择」。跨页选择会保留。
![AI 生成规则 · 选择记录](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/ai-rule-select.png)
2. **预览规则**：AI 依据所选记录的**类型、备注、交易渠道、已有分类与标签**归纳出规则建议，展示规则名称、关键词、目标分类与标签、理由。名称与关键词可编辑，勾选后点击「创建勾选规则」批量创建；系统会自动创建建议中不存在的新分类与标签。
![AI 生成规则 · 预览规则](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/ai-rule-preview.png)
::: tip 与已有规则去重
AI 建议若与**数据库中已有规则重复**（按「类型 + 关键词 + 分类 + 标签集合」判定），会标注「**已存在**」，**默认不勾选且不可勾选**，无法导入，避免产生重复规则。
:::
## 示例
| 规则名 | 条件 | 结果 |
|---|---|---|
| 星巴克归入餐饮 | 关键词「星巴克」、类型支出 | 分类：餐饮；标签：咖啡 |
| 滴滴出行归入交通 | 关键词「滴滴」、类型支出 | 分类：交通 |
| 大额支出标记 | 金额 ≥ 500、类型支出 | 标签：大额消费 |
## 使用建议
- 先建立少量高频规则（餐饮、交通、外卖等），再逐步补充。
- 关键词尽量选择稳定、唯一的商户或商品名，避免误命中。
- 同一笔记录可能命中多条规则，分类取最优先的一条，标签会全部应用。
guide/settings.md
+71
View File
@@ -0,0 +1,71 @@
# 系统设置
系统设置通过右上角用户菜单 →「系统设置」进入，包含六个配置面板。
![系统设置](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/settings.png)
## 数据库配置
![数据库配置面板](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/panel-database.png)
- **数据库类型**：SQLite / MySQL。
- **SQLite**：数据库文件路径（相对于服务运行目录）。
- **MySQL**：主机、端口、数据库名、用户名、密码。
- 提供「测试连接」与「保存并应用」。保存后立即生效并自动建表；已配置时密码留空表示不修改。
系统支持启动后再配置数据库：未配置时前端会引导进入初始化页面，无需启动前准备。登录后也可随时切换数据库，切换后原数据库数据保留、不做自动迁移。
## 注册设置
![注册设置面板](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/panel-registration.png)
控制是否开放注册：
- 系统**无任何用户**时始终允许创建首个账号。
- 关闭后新用户无法注册（登录页不再显示注册入口）。
## 账单来源统计默认值
![账单来源统计默认值面板](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/panel-bill-source-stats.png)
按**账单来源**分别设置导入时「是否计入统计」的默认值，用于避免同一笔消费在多来源账单中重复统计：
- 每个来源一个开关：**计入统计 / 不计入统计**。
- 默认策略：**微信、支付宝**计入，**美团、淘宝、京东、招商银行、交通银行**不计入。
- 不计入的记录仍会导入，只是不参与统计；导入预览页仍可逐条或批量修改。
- 默认值按**当前账号**保存，仅影响当前用户的账单导入。
> 解析器判定为「不计收支/中性」的行始终不计入，不受此处默认值影响。
## 外观设置
![外观设置面板](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/panel-display.png)
选择「不计入统计」的记录在[收支记录](/guide/transactions)列表中的展示方式：
- **删除线（默认）**：整行加删除线，类型与金额列保持原样。
- **灰色标签**：类型列显示灰色「不计入」标签，金额列置灰且不显示正负号。
面板内提供**实时预览**，切换选项即可看到效果；该偏好按**当前账号**保存，登录后生效。
## AI 模型配置
![AI 模型配置面板](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/panel-ai.png)
- **启用 AI 建议**：总开关，关闭后不发起任何 AI 请求。
- **API Key**：DeepSeek 的 API Key（已配置时留空表示不修改）。
- **接口地址**：默认 `https://api.deepseek.com`。
- **模型**：默认 `deepseek-chat`。
- 提供「保存」与「测试连接」。
- 右上角「使用情况」可查看 AI 调用统计与明细，详见 [AI 能力](/guide/ai)。
## 定时通知
![定时通知面板](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/panel-notification.png)
配置账单导入提醒的周期、时间与推送渠道（Server 酱 / 邮箱），并可查看发送日志。详见[定时提醒与通知](/guide/notifications)。
## 相关
- [系统日志](/guide/logs)：查看访问、登录与运行日志。
- [快速开始](/guide/getting-started)：数据库配置与注册登录。
guide/transactions.md
+193
View File
@@ -0,0 +1,193 @@
# 收支记录
「收支记录」页面用于查看和管理每一笔收入与支出。
![收支记录](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/transactions.png)
## 顶部操作
| 按钮 | 功能 |
|---|---|
| 排序 | 交易时间（新→旧 / 旧→新）、金额（高→低 / 低→高） |
| 一键设置 | 对当前表格展示的记录批量设置分类、计入统计与标签 |
| 批量删除 | 删除表格中勾选的记录 |
| 导入账单 | 打开账单导入弹窗 |
| 导出 Excel | 按当前筛选条件导出 |
| 刷新 | 按当前筛选条件与页码重新加载列表 |
| 智能记账 | 用一句话描述收支，AI 解析后预填表单（需启用 AI） |
| 新增记录 | 手动新增一笔记录 |
## 账单导入
「收支记录」页支持把支付宝、微信、美团、淘宝、京东、招商银行、交通银行的账单文件解析并导入为收支记录。
![导入账单弹窗](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/import-bill.png)
### 入口
| 入口 | 形式 | 说明 |
|---|---|---|
| 收支记录页「**导入账单**」按钮 | 弹窗 | 桌面端常用 |
| 通知邮件中的链接 `/bill-import` | 独立页 | **仅由通知邮件直达**，面向手机；独立页面（非弹窗），元素精简、系统内无其他入口 |
> `/bill-import` 是「定时通知」邮件里附带的直达上传页，方便在手机上直接上传账单，不会从系统内其他页面跳转进入。
### 支持的账单类型与格式
| 账单类型 | 支持格式 |
|---|---|
| 支付宝 | `.csv`、`.zip` |
| 微信 | `.xlsx`、`.zip` |
| 美团 | `.csv`、`.zip` |
| 淘宝 | `.xlsx` |
| 京东 | `.csv`、`.zip` |
| 招商银行 | `.csv`、`.pdf`、`.zip` |
| 交通银行 | `.xls`、`.zip` |
各平台账单的导出方法见[账单类型与获取](/guide/bills/overview)。
### 导入流程
导入采用「解析预览 → 确认导入」两步，先解析不落库，确认后才写入。
**第一步：选择类型与文件**
1. 选择账单类型（默认记住上次选择）。
2. 点击或拖拽上传账单文件。
3. 点击「解析」。
切换账单类型会清空已选文件；页面会提示该类型支持的格式与在对应 App 中的导出路径。若上传的是**加密压缩包**，解析时会弹出密码输入框，输入后重新解析。
**第二步：解析预览**
![账单解析预览](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/bill-parse-preview.png)
- **默认归类**：可为本次导入设置默认的支出分类、收入分类与默认标签。
- **筛选**：关键字、类型（收入/支出/不计入）、状态（可导入/已存在/不可导入）、金额区间。
- **逐行勾选**：默认勾选解析器建议的行；只有「可导入」的行可勾选。
- **计入统计**：可对勾选行批量「设为计入 / 设为不计入」，建议按来源设置（见下）。
- **预览列**：交易时间、类型、计入统计、金额、交易对方、商品名称、状态、**匹配规则与建议**。
::: tip 按来源设置计入统计
- **微信、支付宝**来源默认**计入**；**其他**来源（银行、美团、淘宝、京东等）默认**不计入**——它们往往最终走微信/支付宝支付。
- **例外**：工资、奖金等明确收入应计入。
:::
::: tip 去重
系统按「用户 + 交易号」去重。已存在于系统中的交易会标记为「已存在」，默认不勾选，避免重复导入。
:::
**第三步：导入结果**
显示成功、跳过、失败的数量与明细消息。完成后可在下方表格中查看。
### 常见问题
- **解析失败**：确认账单类型与文件格式是否匹配；银行账单请使用系统支持的导出格式。
- **需要解压密码**：部分账单压缩包在导出时设置了密码，需在解析时输入。
- **部分行不可导入**：可能是金额/时间字段无法解析，或该交易号已存在。
- **重复导入**：同一账单重复导入时，已存在的交易会被跳过。
## 筛选与 AI 智能查询
**常用筛选**：类型、分类（含「未分类」）、日期范围、备注关键字、交易渠道。
**更多筛选**：标签（含「无标签」）、计入统计、金额区间。
启用 AI 后，顶部会出现 **AI 智能查询**输入框，可用自然语言查询，例如：
- 「上个月餐饮」
- 「超过500的支出」
- 「待报销的支出」
- 「微信支付」
解析结果会直接应用为筛选条件并立即查询。筛选条件与每页条数、排序方式会自动记忆，下次进入自动还原。
## 表格与行操作
表格展示：交易时间、类型、分类、金额、交易渠道、备注、标签、计入统计开关与操作。
- **备注隐藏**：可将敏感备注持久隐藏为 `******`，需要时临时「查看」或「取消隐藏」。
- **计入统计**：行内开关可直接切换；关闭后该记录不纳入月度统计（适合借款、转账等），行内会以删除线标示。
- **行操作**：编辑、查看「原始数据」（账单导入时的原始字段，以 JSON 展示）、删除。
分页支持每页 10/20/50/100/200/500 条。
## 查看原始数据
账单导入时，系统会完整保留每笔交易在原始账单中的字段（以 JSON 存储）。在记录行点击「**原始数据**」即可查看，用于核对金额、交易状态、对方账号、交易类型等明细。
- 仅**账单导入**的记录有原始数据；**手动新增**的记录没有，该按钮不可用。
- 原始数据是排查导入异常、核对账单的重要依据。
## 一键设置（批量设置）
对**当前表格展示的记录**批量操作：
![一键设置弹窗](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/batch-set.png)
- 设置支出分类 / 收入分类。
- 设置是否计入统计。
- 添加标签 / 移除标签。
- 启用 AI 时，可选择建议范围（分类与标签 / 仅分类 / 仅标签）并点击「AI 智能建议」，由 AI 生成建议后进入 AI 建议弹窗。
## AI 建议弹窗
展示每条记录的建议分类、建议标签与理由，默认全选，可逐条取消。若建议中包含系统中不存在的分类或标签，会以「新建」标记，确认后自动创建。应用后分类会被覆盖、标签会被追加。
## AI 智能记账
在「智能记账」弹窗中用自然语言描述一笔收支，例如「昨天中午吃饭 35 支付宝」，AI 会解析为类型、金额、分类、交易渠道、时间、备注、标签等字段，并预填到新增记录表单，确认后保存。
![AI 智能记账弹窗](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/ai-record.png)
## 手动添加记录
1. 在收支记录页右上角点击「**新增记录**」。
2. 在弹窗中填写表单：
| 字段 | 说明 |
|---|---|
| 类型 | 支出 / 收入 |
| 分类 | 新增时必填 |
| 金额 | 大于 0 |
| 交易渠道 | 可选 |
| 交易时间 | 默认当前时间 |
| 备注 | 可选 |
| 标签 | 可选，可多选 |
| 计入统计 | 默认开启；关闭后不纳入统计 |
3. 点击「确定」保存。
![新增记录弹窗](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/add-record.png)
## 编辑记录
在记录行点击「编辑」即可修改记录，弹窗字段与新增一致；编辑时允许不设置分类。
![编辑记录弹窗](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/edit-record.png)
### 编辑时的 AI 辅助
启用 AI 后，编辑弹窗中的**分类**与**标签**旁会出现 AI 辅助按钮（与新增记录一致）：
| 按钮 | 作用 |
|---|---|
| 分类 · **AI 推荐** | 根据当前类型、金额、交易渠道、备注，从已有分类中推荐并填入 |
| 分类 · **AI 新建** | 根据当前账单信息生成新分类；确认「保存并选用」后创建并选中，若已存在同名同类型分类则直接选中 |
| 标签 · **AI 推荐** | 推荐已有标签并追加（自动去重） |
| 标签 · **AI 新建** | 生成新标签（含建议颜色），确认后创建并选中；同名标签直接选中 |
> 「AI 新建」需先填写备注或金额，便于模型理解；生成结果会显示确认条，点击「保存并选用」才真正创建。
编辑完成后点击「确定」保存。其他 AI 能力（批量建议、智能记账、智能查询）见 [AI 能力](/guide/ai)。
::: tip 计入统计
「计入统计」用于区分真实消费与资金流转，建议**按账单来源**设置，避免多来源重复统计：
- **微信、支付宝**来源：默认**计入**（除非有特殊情况）。
- **其他**来源（银行、美团、淘宝、京东等）：默认**不计入**——这些渠道的扣款往往最终走微信/支付宝，重复计入会导致统计翻倍。
- **例外**：工资、奖金等明确收入应计入。
此外，借款、信用卡还款、账户间转账等资金流转也建议关闭该开关，避免统计失真。
:::