noteTb: 316
This data as json
| id | user_id | content | tags | created_at | updated_at | enable | pinned | folder_id | comment | position | visibility |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 316 | 1 1 | # 财务秘书规划 **作者**：Hermes **版本**：1.0 **状态**：方案阶段，未实施 --- ## 一、目标 在财务后台页面（`/company/`）右上角加一个「呼叫秘书」按钮，点击展开 AI 聊天面板。秘书能查询公司所有财务数据，干活不闲聊。 参考：keng 项目的 Lucy（`lucy.py` + `lucy.html`），但去掉人设，纯粹工具人。 --- ## 二、架构总览 ``` 用户浏览器 → Nginx → /company/api/secretary/ → secretary.py (:8904) │ ┌─ LLM (SiliconFlow) ─┐ │ │ 函数调用 ←────────────→ 飞书 API (数据查询) (Bitable) ``` ### 数据流 1. 用户输入问题 → 前端 POST `/api/secretary/chat` 2. 后端发给 LLM，LLM 判断需要调哪个查询函数 3. 后端执行查询（飞书 API / 本地文件） 4. 查询结果 + 原始问题 → 再发给 LLM 生成自然语言回答 5. 回答返回前端显示 --- ## 三、数据 API 设计 秘书通过 **Function Calling** 模式工作：LLM 决定调用哪个函数，后端执行后把结果注入对话。 ### 3.1 函数清单（10 个） | 函数 | 用途 | 数据源 | |------|------|--------| | `query_ledger(platform?, date_range?, direction?)` | 查总流水 | 飞书 总流水tb | | `query_sales(platform?, date_range?)` | 查销售数据 | 飞书 销售单tb | | `query_payments(status?)` | 查付款申请状态 | 飞书 付款申请tb | | `query_expenditure(platform?, date_range?)` | 查三地支出 | 飞书 三地支出tb | | `compare_platforms(date_range)` | 各平台对比 | 飞书 总流水tb | | `check_anomalies()` | 异常检测 | 总流水+付款+销售 | | `get_price_rules(product_name?)` | 查价格规则 | 飞书 价格tb | | `get_monthly_report(year, month)` | 读取月报表 | 本地 output.xlsx | | `search_transactions(keyword)` | 关键词搜索流水 | 飞书 总流水tb | | `get_recent_summary(days)` | 近N天汇总 | 飞书 总流水tb | ### 3.2 Function Calling 示例 ``` 用户: "抖音5月卖了多少？" → LLM 判断需要 function=query_sales, args={platform:"dy", date_range:"2026-05"} → 后端调飞书 API，拿到 48 条销售记录 → LLM 回复: "抖音2026年5月销售额 ¥XX,XXX.XX，共 48 笔订单（来源：总流水tb）" ``` --- ## 四、前端设计 ### 4.1 入口按钮 topbar 右侧加按钮 `💬 呼叫秘书`： - 样式与导航按钮一致 - 打开时高亮（蓝色），关闭时灰色 - 位置：退出按钮左边（`margin-left: auto` 前） ### 4.2 聊天面板 ``` 桌面端：右侧滑出面板，宽 420px，全屏高 移动端：底部弹出，高 60vh ┌─ 财务秘书 ✕ ─┐ ├──────────────────────────────────┤ │ 💬 有什么可以帮你的？ │ │ │ │ 👤 抖音5月销售额？ │ │ 🤖 抖音2026年5月销售额 ¥xxx │ │ 共 48 笔订单 │ │ │ │ [快捷: 平台对比 | 异常检查 | ...] │ ├──────────────────────────────────┤ │ [输入问题... ] [发送] │ └──────────────────────────────────┘ ``` ### 4.3 快捷按钮 预设问题快速填入： - "本月各平台销售额对比" - "检查异常交易" - "最近7天付款申请" --- ## 五、系统提示词 ``` 你是财务秘书，专门查询和分析公司财务数据。 规则： - 只回答财务、数据、报表相关的问题 - 问无关问题直接说"我只负责财务查询" - 回复简洁专业，中文，附带数据来源 - 不确定的事不编造，说"我需要查一下数据" - 金额用 ¥ 符号，保留两位小数 - 对比数据用表格呈现 你可以查询： - 总流水、销售、付款、支出等所有财务数据 - 按平台(dy/jd/pdd/tb/tgc/vx/xhs)、日期范围、收支方向筛选 - 产品价格规则(产地/规格) - 每月报表汇总 ``` --- ## 六、技术实现 ### 6.1 新文件 | 文件 | 用途 | |------|------| | `secretary.py` | FastAPI 后端，端口 8904 | | `feishu_client.py` | 飞书 API 公共模块（从 merge.py 提取） | | `html/` 内嵌代码 | 聊天面板 HTML/CSS/JS（写在 index.html 中） | ### 6.2 复用 - LLM：config.ini `[llm]` 已有 SiliconFlow DeepSeek-V3.2 - 飞书 API：从 `merge.py` 提取 `get_token/list_tables/read_bitable_all` - 样式：复刻 Lucy 聊天 UI 骨架，配色改为蓝白 ### 6.3 部署 ``` Nginx: location /company/api/secretary/ → proxy_pass http://127.0.0.1:8904/api/ Systemd: secretary.service WorkingDirectory=/home/project/company ExecStart=python3 -m uvicorn secretary:app --host 127.0.0.1 --port 8904 ``` ### 6.4 安全 - 秘书**只有读权限**，不改任何数据 - 不与现有 main.py/merge.py 互相调用，独立进程 - 错误处理友好，飞书 API 挂了就告知用户稍后再试 --- ## 七、示例对话 ``` Q: 这个月抖音卖了多少钱？ A: 2026年5月(截至14日)抖音平台销售额 ¥XX,XXX.XX，共 48 笔订单。来源：总流水tb Q: 哪个平台利润最高？ A: | 平台 | 销售额 | 支出 | 利润 | | dy | ¥xxx | ¥xx | ¥xx | | pdd | ¥xxx | ¥xx | ¥xx | 目前利润最高的是 dy 平台。来源：总流水tb + 三地支出tb Q: 查一下异常 A: 发现 2 条异常： 1. 付款申请#xxx 已删除但仍付款，¥xxx 2. 付款申请#xxx 审批中但已付款，¥xxx 来源：总流水tb + 付款申请tb Q: 牛排价格规则？ A: 产品「牛排」：南宁/200g/¥xx, 越南/150g/¥xx。来源：价格base.价格tb ``` --- ## 八、实施步骤 | 步骤 | 内容 | 预估 | |------|------|------| | 1 | 提取 `feishu_client.py` — 从 merge.py 抽出飞书 API 公共模块 | 30min | | 2 | 写 `secretary.py` — FastAPI + Function Calling + LLM | 1h | | 3 | 前端按钮 + 聊天面板 — 在 index.html 加 UI | 1h | | 4 | Nginx + systemd 配置 | 15min | | 5 | 测试示例对话 | 30min | **总计首次实施：约 3 小时。** --- ## 九、对比 Lucy | 维度 | Lucy（keng） | 财务秘书（company） | |------|-------------|-------------------| | 人设 | 33岁少妇，闷骚 | 无，纯工具 | | 数据源 | keng SQLite | 飞书 Bitable | | 功能 | 整理文本、管笔记 | 查财务、比数据 | | LLM 模式 | 单轮对话 | Function Calling | | 配色 | 深紫 | 蓝白 | | 写权限 | 有 | 无（只读）| --- ## 附录：飞书数据表结构参考 **BASE_APP_TOKEN = ZgGJb6ioEalKSps8Fg7cocWmnUf** | 表名 | 用途 | 关键字段 | |------|------|----------| | 总流水tb | 全部财务流水 | 日期, 平台, 店铺, 资金流向, 金额, 内部, 申请编号 | | 付款申请tb | 付款审批 | 申请编号, 金额, 状态(审批中/已通过/已删除) | | 销售单tb | 销售记录 | 商品, 金额, 平台, 日期 | | 内部付款tb | 内部转账 | 金额, 日期, 用途 | | 三地支出tb | 三地归类支出 | 产品名, 产地, 金额 | **PRICE_APP = M4cbbSEItaKCkysrDJQc5g7Snuc** | 表名 | 用途 | 关键字段 | |------|------|----------| | 价格tb | 价格规则 ~126条 | 产品名, 产地, kw_and, kw_or, kw_not, 长尾词 | | 特殊产品tb | 特殊产品兜底 | 同上 | **LLM 配置（config.ini）** - Provider: SiliconFlow - Model: deepseek-ai/DeepSeek-V3.2 - API Key: sk-okmswwhksmkhzsvwcyaiahizvdwfesrponuingxemkfeyiun | ["财务", "AI", "秘书"] | 2026-05-15 16:50:57 | 2026-05-18 23:26:07 | T | F | 13 | public |