feat: 补充图片记账、交易渠道管理与前端偏好文档

- 新增「交易渠道管理」指南与「前端用户偏好」开发文档，并加入侧边栏导航 - 图片记账：补充多图上传、实时识别进度、结果勾选导入与「来源图片」回看，AI 配置新增视觉模型说明 - 数据模型补充 t_channel、t_ai_config/t_ai_image 等表与「类型+金额+时间」去重键说明，表数更新为 21 张 - API 文档补充 /api/channel、/api/transaction/batch、/api/ai/record/image(/stream)、/api/ai/image、/api/ai/channel 等接口 - 截图脚本新增渠道页、图片记账、来源图片与渠道 AI 辅助截图，并放宽导航超时
2026-09-21 22:19:55 +08:00
parent a4ae7ac979
commit d2e4a51f2b
20 changed files with 557 additions and 40 deletions
@@ -18,7 +18,10 @@
 - 智能查询 / 统计：你输入的自然语言，以及分类与标签名称；
 - 智能记账：你输入的一句话；
 - 生成分类/标签、推荐 Emoji/颜色：你输入的名称或描述；
- 生成规则：所选记录的类型、备注、交易渠道、已有分类与标签（不含金额与原始账单数据）。
+- 生成规则：所选记录的类型、备注、交易渠道、已有分类与标签（不含金额与原始账单数据）；
+- 图片记账：你**主动上传**的账单/支付截图会**整张**发送给视觉模型（可能含金额、交易对方、订单号等），视为你主动提供的输入。
+
+图片同时会保存在本地（`data/ai-images/`），仅本人可查看；请勿上传包含他人敏感信息的图片。

 API Key 仅保存在本地数据库中，仅用于向你配置的接口地址发起请求，不会随上述数据一并外发。

@@ -28,7 +31,7 @@ API Key 仅保存在本地数据库中，仅用于向你配置的接口地址发

 - 开启「启用 AI 建议」。
 - 填写 **API Key**。
- 可选修改 **接口地址**（默认 `https://api.deepseek.com`）与**模型**（默认 `deepseek-chat`）。
+- 可选修改 **接口地址**（默认 `https://api.deepseek.com`）、**模型**（默认 `deepseek-chat`）与**视觉模型**（默认 `deepseek-flash`，用于图片记账）。
 - 点击「测试连接」验证配置。

 ![系统设置](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/settings.png)
@@ -38,10 +41,12 @@ API Key 仅保存在本地数据库中，仅用于向你配置的接口地址发
 | 功能 | 入口 | 说明 |
 |---|---|---|
 | 分类/标签建议 | 收支记录 → 一键设置 → AI 智能建议 | 对当前页记录批量建议分类与标签，可一键采纳 |
-| 单条建议 | 新增/编辑记录 → AI 推荐 | 推荐已有分类或标签 |
+| 单条建议 | 新增/编辑记录 → AI 推荐 | 推荐已有分类、标签或交易渠道 |
 | 智能查询 | 收支记录 → AI 智能查询 | 自然语言解析为筛选条件 |
-| 智能记账 | 收支记录 → 智能记账 | 一句话解析为一笔记录 |
+| 智能记账（文字） | 收支记录 → 智能记账 → 文字记账 | 一句话解析为一笔记录 |
+| 智能记账（图片） | 收支记录 → 智能记账 → 图片记账 | 上传一至多张账单/支付截图，实时识别为多条记录，勾选后批量导入 |
 | 生成分类 | 分类管理 → AI 生成 | 由用途描述生成分类 |
+| 生成渠道 | 新增/编辑记录 → 交易渠道 → AI 新建 | 由账单描述生成渠道名称并创建 |
 | 推荐 Emoji | 分类管理 → AI 推荐 | 为分类推荐 Emoji 图标 |
 | 推荐颜色 | 标签管理 → AI 推荐 | 为标签推荐颜色 |
 | 生成规则 | 规则管理 → AI 生成规则 | 由已打标签的记录归纳分类与标签规则 |
@@ -66,10 +71,36 @@ API Key 仅保存在本地数据库中，仅用于向你配置的接口地址发

 ## 智能记账

-在「智能记账」弹窗中描述一笔收支，AI 解析出类型、金额、分类、交易渠道、时间、备注、标签等字段，并预填到新增记录表单，确认后保存。
+「智能记账」弹窗提供「**文字记账**」与「[图片记账](#图片记账)」两个标签页，再次打开时会记住上次使用的方式。
+
+在「文字记账」中描述一笔收支，AI 解析出类型、金额、分类、交易渠道、时间、备注、标签等字段，并预填到新增记录表单，确认后保存。

 ![AI 智能记账弹窗](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/ai-record.png)

+## 图片记账
+
+在「智能记账」弹窗切换到「**图片记账**」标签页，上传账单或支付截图，AI 会调用**视觉模型**一次性识别其中的每一笔交易。
+
+![图片记账](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/ai-record-image.png)
+
+- **多图上传**：一次最多 **5 张**，单张不超过 **10MB**、总大小不超过 **30MB**；支持 JPEG / PNG / GIF / WebP。
+- **粘贴上传**：也可按 `Ctrl+V`（Mac 为 `⌘V`）直接粘贴剪贴板中的图片。
+- **补充说明**（可选）：在下方输入框补充提示（如「这是 9 月的账单」），帮助模型理解。
+- 点击「识别图片」后，弹窗内会**实时显示识别进度**（校验图片、保存、调用模型、解析、查重等步骤），耗时较长的识别过程可见可控。
+- 识别完成后进入**结果弹窗**：
+
+![图片记账结果](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/ai-record-result.png)
+
+- 结果以表格逐条展示，**默认全选**（疑似重复项默认不勾选），可直接编辑**类型、金额、分类、时间、备注**。
+- **来源图**列标注该笔交易来自第几张上传图片；**重复**列标记与已有记录或本批其它记录「类型+金额+时间」一致的疑似重复项。
+- **原始数据**列可查看模型从图片中提取的原始字段（时间、对方、商品、订单号等），用于核对。
+- 顶部摘要说明识别到的账单内容；勾选后点击「导入勾选」批量写入收支记录（导入时会再次按去重键跳过重复）。
+- 未识别到有效交易时会给出提示，不会写入任何记录。
+
+> 图片记账使用的是视觉模型，可在「系统设置 → AI 模型配置」中单独配置（默认 `deepseek-flash`）。详见[系统设置](/guide/settings)。
+
+导入后的记录在[收支记录](/guide/transactions)页的「**来源图片**」列可回看原图（默认加载缩略图，可切换为原图）。
+
 ## AI 统计搜索

 在统计面板顶部的 AI 搜索框中用一句自然语言描述统计意图，例如「上个月餐饮花了多少」「近半年交通支出趋势，按周看」。系统会解析为**时间范围、收支类型、分类、标签、交易渠道、金额区间、备注、统计口径与趋势粒度**并自动回填、刷新图表。详见[统计面板](/guide/dashboard)。
@@ -0,0 +1,69 @@
+# 交易渠道管理
+
+「交易渠道」用于标记一笔收支的付款或收款途径，既包括账单导入时的来源，也包括人工记账时选择的渠道。系统内置一组常用渠道，并支持按账号自定义。
+
+## 入口
+
+在[收支记录](/guide/transactions)页顶部操作区点击「**渠道管理**」进入（独立页面，不占用左侧菜单）。
+
+![交易渠道管理](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/channels.png)
+
+页面顶部提供返回按钮，可一键回到收支记录页。
+
+## 内置渠道
+
+以下渠道由系统内置，无需创建，名称随界面语言自动显示：
+
+| 编码 | 名称 |
+|---|---|
+| `ALIPAY` | 支付宝 |
+| `WECHAT` | 微信 |
+| `MEITUAN` | 美团 |
+| `TAOBAO` | 淘宝 |
+| `JD` | 京东 |
+| `CMB` | 招商银行 |
+| `BOCOM` | 交通银行 |
+| `CASH` | 现金 |
+
+> 账单导入时，系统会按账单来源自动写入对应的内置渠道；人工记账默认可选「现金」或任意自定义渠道。
+
+## 自定义渠道
+
+除内置渠道外，你可以新建自己的渠道（例如「某张储蓄卡」「公司报销」等）。
+
+### 新建渠道
+
+点击右上角「**新建渠道**」，输入名称后确认。
+
+![新建渠道](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/channel-create.png)
+
+- 渠道名称在**当前账号内不可重复**。
+- 渠道编码由系统生成且**稳定不变**，交易记录按编码关联。
+
+### 重命名渠道
+
+在列表行点击「编辑」即可改名。**改名不影响历史账单**——所有已使用该渠道的记录会同步显示新名称。
+
+### 删除渠道
+
+在列表行点击「删除」即可删除。
+
+- 若该渠道**已被账单使用**，系统会拒绝删除并提示使用数量，避免历史记录出现无效渠道。
+- 列表中的「使用账单数」列可直观看到每个渠道被多少笔记录使用。
+
+## 在哪些地方使用
+
+自定义渠道创建后，可在以下场景直接选用：
+
+- **新增 / 编辑记录**：交易渠道下拉中出现在内置渠道之后。
+- **筛选与统计**：收支记录页筛选、统计面板的渠道维度与筛选均可选择自定义渠道，图表与分组会展示其名称。
+- **AI 能力**：智能查询、统计搜索与智能记账会把当前账号的自定义渠道一并作为可选渠道；新增/编辑记录时还可用「渠道 · AI 推荐」选择已有渠道，或「渠道 · AI 新建」由描述生成并创建渠道。
+- **导出**：Excel 导出时渠道列展示自定义渠道名称。
+
+> 删除前请先确认没有账单仍在使用该渠道；如需保留历史，建议改名而非删除。
+
+## 相关
+
+- [收支记录](/guide/transactions)：记账、筛选与账单导入。
+- [统计面板](/guide/dashboard)：按渠道维度统计。
+- [AI 能力](/guide/ai)：自然语言查询与图片记账。
@@ -12,12 +12,13 @@

 - [收支记录](/guide/transactions)：记录管理、筛选、批量操作、账单导入、AI 建议与记账
 - [分类与标签](/guide/categories-tags)：分类与标签的维护与使用建议
+- [交易渠道管理](/guide/channels)：内置渠道与自定义渠道的新建、改名与删除
 - [规则管理](/guide/rules)：按关键词/金额/类型自动归类打标，支持 AI 生成规则、搜索与分页
 - [邮箱账单](/guide/email-bills)：IMAP 自动拉取账单邮件

 ## 智能与自动化

- [AI 能力](/guide/ai)：分类标签建议、自然语言查询与记账、AI 搜索与规则生成、用量统计
+- [AI 能力](/guide/ai)：分类标签与渠道建议、自然语言查询与记账、多图图片记账（实时进度）、AI 搜索与规则生成、用量统计
 - [定时提醒与通知](/guide/notifications)：多渠道账单导入提醒

 ## 系统
@@ -17,10 +17,11 @@
 |---|---|
 | 收支记录 | 增删改查、分页与多条件筛选、批量设置分类/标签、批量删除、计入统计开关、备注隐藏、导出 Excel |
 | 分类与标签 | 收入/支出分类与标签的增删改查，新用户自动获得默认数据，AI 推荐 Emoji 与颜色 |
+| 交易渠道 | 内置渠道 + 自定义渠道的新建/改名/删除，改名不影响历史账单 |
 | 统计图表 | 月度收支、分类占比、收支趋势、交易渠道占比，支持按日/周/月/季/年粒度，点击趋势图可下钻对应明细 |
 | 账单导入 | 七类账单解析、zip 解密、解析预览、按交易号去重、规则建议 |
 | 自定义规则 | 关键词/收支类型/金额区间组合，优先级排序、启用停用，导入时自动应用；支持 AI 生成规则、搜索与分页 |
-| AI 能力 | 分类标签建议、自然语言查询、自然语言记账、AI 统计搜索、AI 生成规则、分类/标签生成、Emoji/颜色推荐、用量统计 |
+| AI 能力 | 分类标签与渠道建议、自然语言查询、文字/多图图片记账、AI 统计搜索、AI 生成规则、分类/标签/渠道生成、Emoji/颜色推荐、用量统计 |
 | 邮箱账单 | 多邮箱 IMAP IDLE 监听、发件人规则识别账单类型、待处理列表先预览再导入 |
 | 定时通知 | 每天/每周/每月提醒，邮箱 SMTP 与 Server 酱渠道，发送日志 |
 | 系统日志 | 访问日志、登录日志、运行日志在线查看，运行日志实时推送，自动清理 |
@@ -13,6 +13,7 @@
 | 收支记录 | `/transactions` | 记录管理与**账单导入** | 左侧菜单 |
 | 分类管理 | `/categories` | 收入/支出分类维护 | 左侧菜单 |
 | 标签管理 | `/tags` | 标签维护 | 左侧菜单 |
+| 交易渠道管理 | `/channels` | 自定义交易渠道维护 | 收支记录页「渠道管理」按钮 |
 | 规则管理 | `/rules` | 自动归类规则 | 左侧菜单 |
 | 邮箱账单 | `/email-bills/*` | 邮箱配置 / 发件人规则 / 待处理账单 | 左侧菜单 |
 | 系统设置 | `/settings` | 数据库 / 注册 / 账单来源统计 / 外观 / AI / 通知配置 | 顶部用户菜单 |
@@ -33,6 +34,8 @@
 - **退出**：清空登录态并返回 `/login`

 > 「模型使用情况」没有独立菜单入口，需从「系统设置 → AI 模型配置 → 使用情况」进入。
+>
+> 「交易渠道管理」同样没有独立菜单入口，需从「收支记录 → 渠道管理」进入。

 ## 典型跳转路径

@@ -41,9 +44,10 @@
 - **查看趋势明细**：统计面板 → 点击「收支趋势」某一列（柱子或该列空白处）→ 收支记录（自动带入时间范围、类型与当前筛选条件）
 - **账单导入**：收支记录 → 点击「导入账单」→ 解析预览 → 确认导入 → 回到收支记录
 - **手机导入**：通知邮件链接 → `/bill-import`（独立页，非弹窗）→ 上传解析 → 确认导入
+- **渠道维护**：收支记录 → 点击「渠道管理」→ 新建 / 改名 / 删除自定义渠道 → 返回收支记录
 - **自动归类**：规则管理配置规则 → 账单导入预览时命中并给出建议
 - **邮箱账单**：邮箱配置 → 发件人规则 → 待处理账单 → 解析 → 导入到收支记录
- **AI 辅助**：系统设置启用 AI → 统计面板「AI 搜索」、收支记录「一键设置 / 智能记账 / AI 查询」、分类与标签「AI 推荐」、规则管理「AI 生成规则」
+- **AI 辅助**：系统设置启用 AI → 统计面板「AI 搜索」、收支记录「一键设置 / 文字·图片记账 / AI 查询」、编辑记录「分类·标签·渠道 AI 推荐与新建」、分类与标签「AI 推荐」、规则管理「AI 生成规则」
 - **系统维护**：顶部菜单 → 系统设置 / 系统日志

 ## 页面关系说明
@@ -53,3 +57,4 @@
  - 收支记录页的「导入账单」**弹窗**（桌面端常用）；
  - 通知邮件直达的 **`/bill-import` 独立页**（面向手机，非弹窗，元素精简，系统内无其他入口）。
 - **系统设置**聚合了数据库、注册、账单来源统计、外观、AI、通知六类配置；模型用量与日志分别从设置页与顶部菜单进入。
+- **交易渠道管理**是收支记录页的附属页，用于维护自定义渠道，维护完成后返回收支记录继续记账或筛选。
@@ -56,6 +56,7 @@
 - **API Key**：DeepSeek 的 API Key（已配置时留空表示不修改）。
 - **接口地址**：默认 `https://api.deepseek.com`。
 - **模型**：默认 `deepseek-chat`。
+- **视觉模型**：默认 `deepseek-flash`，用于[图片记账](/guide/ai#图片记账)。
 - 提供「保存」与「测试连接」。
 - 右上角「使用情况」可查看 AI 调用统计与明细，详见 [AI 能力](/guide/ai)。

@@ -12,6 +12,7 @@
 | 一键设置 | 对当前表格展示的记录批量设置分类、计入统计与标签 |
 | 批量删除 | 删除表格中勾选的记录 |
 | 导入账单 | 打开账单导入弹窗 |
+| 渠道管理 | 进入[交易渠道管理](/guide/channels)页，维护自定义渠道 |
 | 导出 Excel | 按当前筛选条件导出 |
 | 刷新 | 按当前筛选条件与页码重新加载列表 |
 | 智能记账 | 用一句话描述收支，AI 解析后预填表单（需启用 AI） |
@@ -90,7 +91,7 @@

 ## 筛选与 AI 智能查询

-**常用筛选**：类型、分类（含「未分类」）、日期范围、备注关键字、交易渠道。
+**常用筛选**：类型、分类（含「未分类」）、日期范围、备注关键字、交易渠道。交易渠道下拉包含内置渠道与账号下的[自定义渠道](/guide/channels)。

 **更多筛选**：标签（含「无标签」）、计入统计、金额区间。

@@ -105,19 +106,23 @@

 ## 表格与行操作

-表格展示：交易时间、类型、分类、金额、交易渠道、备注、标签、计入统计开关与操作。
+表格展示：交易时间、类型、分类、金额、交易渠道、备注、标签、来源图片、计入统计开关与操作。

 - **备注隐藏**：可将敏感备注持久隐藏为 `******`，需要时临时「查看」或「取消隐藏」。
 - **计入统计**：行内开关可直接切换；关闭后该记录不纳入月度统计（适合借款、转账等），行内会以删除线标示。
- **行操作**：编辑、查看「原始数据」（账单导入时的原始字段，以 JSON 展示）、删除。
+- **来源图片**：图片记账生成的记录会显示「查看（N）」入口，弹窗内先加载缩略图，可按需「加载原图」查看对应截图。
+- **行操作**：编辑、查看「原始数据」（账单导入或图片记账时的原始字段，以 JSON 展示）、删除。
+
+![来源图片弹窗](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/source-images.png)

 分页支持每页 10/20/50/100/200/500 条。

 ## 查看原始数据

-账单导入时，系统会完整保留每笔交易在原始账单中的字段（以 JSON 存储）。在记录行点击「**原始数据**」即可查看，用于核对金额、交易状态、对方账号、交易类型等明细。
+账单导入或图片记账时，系统会完整保留每笔交易在原始账单中的字段（以 JSON 存储）。在记录行点击「**原始数据**」即可查看，用于核对金额、交易状态、对方账号、交易类型等明细。

- 仅**账单导入**的记录有原始数据；**手动新增**的记录没有，该按钮不可用。
+- **账单导入**记录保留原始账单行字段；**图片记账**记录保留模型从截图提取的原始字段。
+- **手动新增**的记录没有原始数据，该按钮不可用。
 - 原始数据是排查导入异常、核对账单的重要依据。

 ## 一键设置（批量设置）
@@ -137,10 +142,15 @@

 ## AI 智能记账

-在「智能记账」弹窗中用自然语言描述一笔收支，例如「昨天中午吃饭 35 支付宝」，AI 会解析为类型、金额、分类、交易渠道、时间、备注、标签等字段，并预填到新增记录表单，确认后保存。
+「智能记账」弹窗提供**文字记账**与**图片记账**两种方式。

 ![AI 智能记账弹窗](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/ai-record.png)

+- **文字记账**：用一句话描述一笔收支，例如「昨天中午吃饭 35 支付宝」，AI 会解析为类型、金额、分类、交易渠道、时间、备注、标签等字段，并预填到新增记录表单，确认后保存。
+- **图片记账**：上传一至多张账单或支付截图（也可 `Ctrl+V` 粘贴），AI 实时识别其中的每一笔交易，生成可编辑的记录列表，勾选后批量导入。
+
+再次打开弹窗会记住上次使用的记账方式。图片记账的用法与限制详见 [AI 能力 → 图片记账](/guide/ai#图片记账)。
+
 ## 手动添加记录

 1. 在收支记录页右上角点击「**新增记录**」。
@@ -151,7 +161,7 @@
   | 类型 | 支出 / 收入 |
   | 分类 | 新增时必填 |
   | 金额 | 大于 0 |
-   | 交易渠道 | 可选 |
+   | 交易渠道 | 可选，含内置渠道与[自定义渠道](/guide/channels)；启用 AI 时可一键推荐或新建 |
   | 交易时间 | 默认当前时间 |
   | 备注 | 可选 |
   | 标签 | 可选，可多选 |
@@ -169,7 +179,7 @@

 ### 编辑时的 AI 辅助

-启用 AI 后，编辑弹窗中的**分类**与**标签**旁会出现 AI 辅助按钮（与新增记录一致）：
+启用 AI 后，编辑弹窗中的**分类**、**标签**与**交易渠道**旁会出现 AI 辅助按钮（与新增记录一致）：

 | 按钮 | 作用 |
 |---|---|
@@ -177,6 +187,10 @@
 | 分类 · **AI 新建** | 根据当前账单信息生成新分类；确认「保存并选用」后创建并选中，若已存在同名同类型分类则直接选中 |
 | 标签 · **AI 推荐** | 推荐已有标签并追加（自动去重） |
 | 标签 · **AI 新建** | 生成新标签（含建议颜色），确认后创建并选中；同名标签直接选中 |
+| 渠道 · **AI 推荐** | 根据当前类型、金额、渠道、备注，从已有渠道中推荐并填入 |
+| 渠道 · **AI 新建** | 生成新渠道名称；确认「保存并选用」后创建并选中，同名渠道直接选中 |
+
+![编辑记录中的渠道 AI 辅助](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/elements/ai-channel-suggest.png)

 > 「AI 新建」需先填写备注或金额，便于模型理解；生成结果会显示确认条，点击「保存并选用」才真正创建。