Skip to content
BranchesTags

Repository files navigation

飞书零花钱助手

飞书零花钱助手是一个面向家庭场景的 Web 系统，核心交互在飞书群完成，后台提供移动端优先管理页面。

功能概览

  1. 管理员初始化与账号体系（管理员/操作用户）
  2. 小孩管理：姓名、头像、每日额度、余额
  3. 操作用户绑定可控制小孩
  4. 飞书群消息识别：
    • 调整每日零花钱额度
    • 设置额外奖励项目与金额
    • 扣除消费金额（支持负数扣除）
    • 设置每周统计通知时间（每周一）
  5. 机器人主动通知：
    • 金额变动通知
    • 系统操作反馈通知
    • 每周统计通知 + 使用建议
  6. 内置 MCP 服务器：支持四类后台操作工具
  7. 管理后台分区导航：按“小孩/操作员/系统配置/流水/模型/模板/周报”切换

项目结构

backend/ 后端 API 与业务逻辑 frontend/ 移动端优先后台页面 mcp-server/ MCP 工具服务 docs/ 需求、飞书流程、部署文档

本地开发

后端

cd backend npm install npm run dev

前端

cd frontend npm install npm run dev

MCP 服务

cd mcp-server npm install

需要管理员账号 token

set MCP_BACKEND_TOKEN=你的管理员JWT set BACKEND_URL=http://localhost:3000 npm start

容器部署（单容器）

快速开始

使用根目录 docker-compose.yml：

# 1. 复制环境变量示例
cp .env.example .env

# 2. 启动容器（首次，完全自动初始化）

# 3. 启动容器（首次）
docker compose up -d

# 3. 初始化管理员（仅首次，容器自动生成 JWT 密钥）
curl -X POST http://localhost:45174/api/init-admin \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your-secure-password"}'

# 4. 登录并在 UI 中配置：
#    - 飞书群机器人 webhook（在管理后台）
#    - AI 模型配置：DeepSeek API key（在模型管理页面）
#    - 其他小孩、奖励规则等

配置项说明

配置项 位置 说明
飞书 Webhook 系统配置 API 管理员在 UI 中设置
模型 API Key 模型管理页面 支持 DeepSeek、OpenAI、Google
小孩绑定 系统 UI 与飞书用户关联

模型与模板默认行为

  1. 系统会自动生成默认推荐模型 DeepSeek（可修改）。
  2. DeepSeek 默认 API 地址为 https://api.deepseek.com。
  3. 模型配置通过“API Key + API 地址”可直接获取模型列表，再选择模型 ID（也支持手填修改）。
  4. 系统会自动生成默认 MCP 模板（工作总结/日报快报/周报总结/事件报告/优化建议），并保留可编辑能力。

后续更新

数据和 JWT 密钥已持久化到 ./data 目录，重新部署时数据不丢失：

docker compose pull
docker compose up -d

数据持久化结构

./data/
  store.json        # 所有业务数据（小孩、消费、配置等）
  .jwt-secret       # JWT 密钥（首次启动自动生成）
./config/
  # 预留目录，可放置自定义配置文件

GitHub 直接构建镜像

  1. 在 GitHub Actions 执行工作流 Build & Push Images。
  2. 触发构建后确认镜像已推送到 ghcr.io。
  3. 本项目 docker-compose.yml 已固定镜像地址，常规部署无需再手动改镜像参数。

详细步骤见 docs/SYNOLOGY_DEPLOYMENT.md。

飞书侧操作

1. 在飞书开放平台创建自建应用

推荐使用自建应用 WS 长连接模式，服务端主动连接飞书，无需公网 IP 或域名（NAS / 内网服务器直接可用）。

  1. 打开飞书开放平台 https://open.feishu.cn，登录后进入开发者后台
  2. 点击创建自建应用，填写名称，创建完成
  3. 左侧菜单-添加应用能力-开启机器人能力
  4. 左侧菜单-权限管理-勾选并申请以下权限（见下方“权限清单”）
  5. 左侧菜单-事件订阅-选择长连接模式（无需填写回调 URL）
    • 添加事件：im.message.receive_v1（接收消息）
    • 添加事件：card.action.trigger（卡片按钮回调，用于撤销操作）
  6. 页面顶部申请上线提交审核

1.1 权限清单（必须完整）

下表为当前功能依赖的飞书权限，建议一次性全开，避免“部分功能可用、部分功能报错”。

权限标识（Scope） 是否必选 用途 缺失时表现
im:message 必选 接收群消息事件 机器人收不到指令
im:message:send_as_bot 必选 发送反馈卡片/通知卡片 指令识别成功但回传失败
im:resource 必选 上传头像图片到飞书（/im/v1/images） 头像上传失败或无头像
contact:contact.base:readonly 必选 读取通讯录基础信息（/contact/v3/users/:id） 用户信息查询失败/权限报错
contact:user.basic.profile:readonly 必选（本次补充） 通过 basic_batch 获取姓名（/contact/v3/users/basic_batch） 日志出现 code=99991672 Access denied，操作人名称无法稳定获取

重点：contact:user.basic.profile:readonly 是“通过 ID 获取用户姓名”接口所需权限，之前最容易漏掉。

1.2 权限开通后的生效步骤（很多人会漏）

仅在权限管理里勾选还不够，必须完成以下链路：

  1. 开放平台-权限管理：勾选并提交权限申请
  2. 开放平台-版本管理：发布新版本（测试版/正式版）
  3. 飞书管理后台（企业侧）：管理员同意/更新应用授权
  4. 若群内机器人未自动更新权限：移除后重新添加机器人到群

未完成以上步骤时，后端常见日志：

  • Access denied
  • code=99991672

Webhook 模式（备用）：若服务有公网 IP，可在事件订阅页改为回调 URL 模式，填写 http://你的服务IP:45174/api/feishu/events。两种模式只选其一。

2. 接收模式说明

模式 特点 适用场景
WS 长连接（推荐） 服务主动连飞书，无需公网 IP NAS / 内网 / Docker
Webhook 回调 飞书推送到公网 URL 有固定 IP 或域名的服务器

使用 WS 长连接时，服务启动后自动建立连接，无需额外配置回调 URL。

3. 在后台机器人页填写凭证

进入后台-底部菜单机器人-向下滚动到飞书机器人设置

字段 内容 在哪找
飞书接入方式 选自建应用（WS 长连接） -
飞书 App ID cli_ 开头约 20 位 开放平台-应用详情-凭证与基础信息-App ID
飞书 App Secret 与 App ID 同页 开放平台-应用详情-凭证与基础信息-App Secret
Verification Token 约 24 位字符串（Webhook 模式需要） 开放平台-事件订阅-加密策略-Verification Token
Signing Secret 约 24 位字符串（Webhook 模式需要） 开放平台-事件订阅-加密策略-Encrypt Key
默认通知 Chat ID oc_ 开头字符串 见第 4 步

WS 长连接模式只需 App ID 和 App Secret，Verification Token / Signing Secret 可留空。

3.1 快速自检（配置后建议执行）

  1. 在群里发送一条测试消息（如：加20）
  2. 后台运行日志中确认：
    • 无 飞书应用消息发送失败
    • 无 basic_batch ... Access denied
    • 无 头像上传 ... code=234007/权限错误
  3. 收到机器人卡片后确认：
    • 变动操作人有名称（非 未知用户）
    • 头像正常显示

4. 如何获取 Chat ID

  1. 将机器人加入目标飞书群：群设置-机器人-添加机器人-搜索应用名
  2. 进入后台机器人页，编辑已有机器人
  3. 确保已保存 App ID 和 App Secret 后，点击「默认通知 Chat ID」输入框旁的**「获取群列表」**按钮
  4. 从下拉列表中选择目标群，Chat ID 自动填入
  5. 点击保存即可

备用方式：在目标群内发任意消息后，页面底部「最近活跃 Chat ID（只读）」字段会自动记录，可手动复制到默认通知 Chat ID 中。

5. 创建机器人并绑定控制账号

  1. 后台机器人页-右下角加号新增机器人
  2. 填写名称，勾选管理的孩子（可多选）
  3. 填写可控制账号 OpenID（每行一个 ou_ 开头的 ID）
    • 获取方式：飞书 App-我的-关于飞书-开发者工具-个人 OpenID
    • 只有填入的账号才能触发机器人；留空则任意用户均可触发

6. 设置周报通知时间

后台机器人页-向下滚动到周报通知-点击时间框选择时间-保存通知时间 每周一该时间点自动向默认 Chat ID 发送上周统计。

7. 设置每日零花钱发放时间

每个孩子可独立设置发放时刻（精确到分钟）：

  1. 后台-底部菜单孩子-点击进入孩子详情
  2. 表单中找到「每日发放时」和「每日发放分」两个字段
  3. 填入希望的发放时刻（如 8 时 0 分 = 每天早上 8:00）
  4. 保存后，定时任务每分钟检查一次，到时自动发放并推送飞书通知

8. 飞书群操作指令

指令示例 说明
设置小明每日零花钱 12 元 调整每日发放额度
设置小明奖励项目家务 5 元 添加奖励项目
扣除小明 8 元 买零食 扣除消费
小明完成家务 触发奖励发放
设置每周统计通知 20:30 修改周报时间

注意：发消息账号必须在机器人可控制账号 OpenID 中，未绑定账号消息被自动忽略。

9. 卡片按钮说明（撤销操作）

系统在推送金额变动通知卡片时，卡片底部会出现「↩ 撤销此操作」按钮。在 30 分钟内点击可自动反向操作（如撤销一笔 +10 元则扣除 10 元）。撤销本身也会产生新通知并再次出现撤销按钮。

10. 主动通知说明

机器人会向默认 Chat ID 推送：

  • 每次金额变动明细（含对象、金额、类型、原因、操作人、当前余额）
  • 操作结果反馈
  • 每周一统计汇总（含 AI 建议）

11. 消息过滤说明

系统自动忽略：

  • 机器人自身消息
  • 发送者不在可控制账号列表中（controllerOpenIds 不为空时生效）

About

每天自动给小朋友的虚拟存钱罐存入零花钱，并通过飞书机器人和AI自动记账

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages