chore: 初始化文档站仓库

2026-09-21 13:38:20 +08:00
commit a4ae7ac979
58 changed files with 4622 additions and 0 deletions
@@ -0,0 +1,80 @@
+# AI 集成
+
+系统集成 **DeepSeek** 大模型，用于分类打标、自然语言查询与记账等场景，并完整记录调用用量。
+
+## 客户端
+
+`DeepSeekClient` 基于 **OpenAI 官方 Java SDK**（`com.openai:openai-java`）调用，通过自定义 `baseUrl` 指向 DeepSeek 的 OpenAI 兼容接口：
+
+- 使用 `OpenAIOkHttpClient`，按 `(baseUrl, apiKey)` 缓存客户端（上限 32，超出后清空重建）。
+- `temperature = 0.2`，`response_format = {"type":"json_object"}`，非流式，`maxRetries(0)`，请求超时 60 秒。
+- 取 `choices[0].message.content` 与 `usage`（输入/输出/总 token；缓存命中 token 取 `promptTokensDetails.cachedTokens`，DeepSeek 私有字段读不到时为 0）。
+- 对外保持 `chat(baseUrl, apiKey, model, systemPrompt, userPrompt)` 与 `DeepSeekResponse` 不变，各 `Ai*ServiceImpl` 无需改动。
+
+配置存储于 `t_ai_config`（每用户一条）：`enabled`、`api_key`、`base_url`（默认 `https://api.deepseek.com`）、`model`（默认 `deepseek-chat`）。API Key 对外脱敏，支持连通性测试。
+
+## 数据外发范围（隐私）
+
+调用大模型时**仅发送功能所需的最小字段**，禁止外发敏感数据：
+
+- **禁止**：`rawData`（账单原始 JSON）、金额、交易号、账户/卡号、姓名、地址、电话等。
+- **允许**：收支类型、交易渠道、备注（必要时截断/脱敏）、分类与标签的名称/ID、用户主动输入的自然语言文本。
+
+## 调用类型
+
+`AiCallType` 定义了 9 类调用，全部记录用量：
+
+| 枚举值 | 含义 |
+|---|---|
+| `SUGGEST` | 交易分类/标签建议（批量 + 单条） |
+| `TEST` | 连接测试 |
+| `QUERY` | 自然语言查询解析为筛选条件 |
+| `RECORD` | 自然语言记账解析为交易记录 |
+| `DECORATE` | 分类 Emoji / 标签颜色建议 |
+| `CATEGORY` | 自然语言生成分类 |
+| `TAG` | 自然语言生成标签 |
+| `RULE` | 由已打标签记录生成分类与标签规则 |
+| `STATISTICS` | 自然语言统计查询解析 |
+
+## 分类/标签建议
+
+`AiSuggestionServiceImpl`：
+
+- 先按「类型 + 交易渠道 + 备注」聚合去重，仅将代表记录送模型；单批 ≤ 100 条、总量 ≤ 500 条，超出则分批调用。
+- 支持严格模式（仅从已有分类/标签中选择）与增强模式（可返回新分类/新标签）。
+- 应用时分类覆盖写入、标签追加；新建分类按「类型 + 名称」去重，新建标签按名称去重并校验颜色格式。
+
+## 自然语言查询
+
+`AiQueryServiceImpl` 在提示词中注入当前分类、标签与当前日期，解析出：类型、交易渠道、分类名、标签名、日期范围预设（今天/昨天/本周/上周/本月/上月/近7天/近30天/今年/去年/自定义/无）、金额区间、备注、是否计入统计、是否未分类等，并在服务端把预设换算为绝对时间。
+
+## 自然语言记账
+
+`AiRecordServiceImpl` 解析类型、金额、分类、标签、交易渠道、交易时间、备注、计入统计等字段；金额无效直接报错，时间缺失回退当前时间。
+
+## 规则生成
+
+`AiRuleServiceImpl` 由用户勾选的**已打标签记录**反推分类/标签规则：
+
+- 仅加载属于当前用户且被勾选的记录（单次 ≤ 500 条），附带其标签名称与分类名；提示词字段为 `type / remark / channel / category / tags`（不含金额与 `rawData`），并对相同组合去重。
+- 解析并校验模型输出（分类 ID 归属与类型、标签归属、名称长度、颜色格式等）。
+- **去重**：按「类型 + 归一化关键词 + 分类 + 排序标签集合」计算签名；与已有规则或本次建议内部重复的条目标记 `duplicate=true`（前端默认不勾选且禁止导入），`apply` 时后端再次校验并跳过。
+
+## 统计搜索
+
+`AiStatisticsServiceImpl` 在提示词中注入分类、标签与当前日期，将自然语言解析为统计面板参数：时间范围（预设→绝对时间）、收支类型、分类、标签、交易渠道、金额区间、备注、统计口径（`statsScope`）与趋势粒度（`dimension`）。
+
+## 用量记录
+
+- 每次调用写入 `t_ai_usage`：调用类型、模型、分析条数、输入/输出/总/缓存 token、是否成功、错误信息、耗时。
+- 记录失败仅告警，不影响主流程。
+- `GET /api/ai/usage` 返回汇总与最近明细，对应「模型使用情况」页面。
+
+## 说明
+
+账单类型识别**不使用 AI**，而是由邮箱账单的**发件人规则**确定，结果确定、可预期。详见[定时通知](/dev/notifications)与[邮箱账单](/guide/email-bills)。
+
+## 相关文档
+
+- [AI 能力（使用说明）](/guide/ai)
+- [整体架构](/dev/architecture)