Feishu Integration for ERPNext

飞书（Lark）与 ERPNext 深度集成插件。扫码登录、Bot 数据录入、卡片审批、消息推送，四合一。

功能

功能	说明
🔐 飞书扫码登录	飞书 OAuth 扫码登录 ERPNext，自动匹配用户（手机号/邮箱/飞书ID）
🤖 Bot 命令录入	飞书群里 @机器人，用命令创建采购订单、销售订单、客户等数据
📋 卡片审批	ERPNext 工作流触发 → 飞书审批卡片 → 点通过/驳回 → 回调完成审批
📢 消息推送	业务事件（PO 提交、收货完成等）自动通知到飞书

架构

飞书开放平台                      ERPNext
──────────                      ───────
  OAuth API  ←── auth.py ──→  扫码登录

  WebSocket  ←── ws_client.py ──→  Bot 消息处理
      ↑                               ├─ 意图解析（命令+LLM）
      │                               ├─ 数据录入（自动填+智能补+卡片补）
      │                               └─ 权限校验（飞书→ERPNext 角色）

  REST API   ←── client.py ────→  发消息、发卡片
              ←── workflow ────→  审批回调
              ←── push ────────→  事件通知

安装

# 1. 获取插件
bench get-app https://github.com/z125316840-code/feishu_integration

# 2. 安装到站点
bench --site your-site.local install-app feishu_integration

# 3. 配置飞书应用 → 见下方配置说明

# 4. 启动 WebSocket 桥
bench feishu start-bridge

配置

1. 飞书开放平台

1. 注册企业自建应用，获取 App ID / App Secret
2. 添加权限：user.auth:user_info_v2:read、im:message、contact:user.email、contact:contact.base:readonly
3. 开通 WebSocket 事件订阅（事件与回调 → WebSocket 长连接）
4. 设置回调 URL：https://你的域名/feishu_callback
5. 发布上线

2. ERPNext 后台

进入「Feishu Settings」：

字段	值
Enabled	✅ 勾选
App ID	飞书应用的 App ID
App Secret	飞书应用的 App Secret
Redirect Domain	站点域名（留空自动获取）
Bot Name	机器人名称，默认 "ERP助手"

可选 NLP 配置：

字段	说明
LLM API Key	OpenAI 兼容 API Key
LLM Endpoint	接口地址，如 https://api.openai.com/v1/chat/completions
LLM Model	模型名，默认 gpt-4o-mini
Enable NLP	✅ 勾选后支持自然语言交互

3. 用户绑定

在 User 列表中为每个需要飞书功能的用户填写 feishu_user_id，或者在 mobile_no 字段填写手机号（首次扫码登录时自动绑定）。

使用

Bot 命令

命令	示例
/po <供应商> <物料> <数量>	/po 华为 服务器 10
/查采购 <编号>	/查采购 PO-00042
/查收货 <编号>	/查收货 PREC-0018
/so <客户> <物料> <数量>	/so 北京云 固态硬盘 100
/查销售 <编号>	/查销售 SO-00015
/库存 <物料>	/库存 螺丝
/待审批	/待审批
/审批通过 <编号>	/审批通过 PO-00042
/审批驳回 <编号> <原因>	/审批驳回 PO-00042 金额不合理
/创建客户 <名称> <联系人> <电话>	/创建客户 北京云科技 王经理 138xxxx
/查客户 <名称>	/查客户 北京云科技
/查工单 <编号>	/查工单 WO-0012
/工单进度 <编号>	/工单进度 WO-0012
/帮助	/帮助

工作流审批

在 ERPNext 中为采购订单等配置工作流，当文档进入待审批状态时，自动推送审批卡片到审批人的飞书。

卡片包含：

• 文档关键字段概览
• ✅ 通过 / ❌ 驳回 按钮
• 查看详情链接

消息推送

在 hooks.py 中配置 doc_events 或在代码中直接调用：

from feishu_integration.bridge.push import send_message, send_card, send_to_role

# 发文本
send_message("admin@example.com", "采购订单 PO-00042 已提交")

# 发卡片
send_card("admin@example.com", card_dict)

# 按角色群发
send_to_role("Purchase Manager", text="新的采购订单待审批")

CLI 命令

bench feishu start-bridge    # 启动 WebSocket 桥
bench feishu stop-bridge     # 停止
bench feishu status          # 查看状态

Procfile 集成

在 bench 目录的 Procfile 中添加，bench start 时自动拉起：

feishu_bridge: bench feishu start-bridge

依赖

• Frappe Framework ≥ V15
• ERPNext ≥ V15
• Python 3.10+
• websocket-client ≥ 1.6.0

必填项处理策略

Bot 创建文档时，必填项分四层处理：

1. 自动推导 — company、posting_date、currency 等从用户默认值和全局设置推断
2. 主数据反查 — 供应商名 → 反查其默认价目表、地址；物料名 → 反查默认单位、仓库
3. 卡片补填 — 仍缺的字段通过飞书卡片表单让用户补充
4. 硬拒绝 — 核心字段缺失且无法补填时提示用户

License

MIT