#Fund Helper

#客户端版本与下载

| JetBrains 插件 | 0.1.1 | JetBrains Release CI | jetbrains-v0.1.1 |

发版命令：./publish-chrome.sh --release · ./publish-vscode.sh --release · ./publish-jetbrains.sh --release · ./publish-desktop.sh --release（详见 文档 · 发版与下载）

#五种使用方式

详见 文档中心 或 chrome-extension/README.md、vscode-extension/README.md、jetbrains-extension/README.md 与 desktop/README.md。

#桌面端下载

说明：安装包由 GitHub Actions 构建并发布到 Releases。首次发布前该页面为空；需先 触发构建 并等待 workflow 完成（约 15–25 分钟）。

| macOS（Universal，M + Intel） | Fund-Helper-0.1.3-macos.dmg | desktop-v0.1.3 Release | | Windows | Fund-Helper-0.1.3-windows-setup.exe | 同上 Release 页 |

构建进度：Actions → Desktop Release

#触发桌面端 CI 构建

# 方式 1：打 tag（已推送 desktop-v0.1.0 时会自动触发）
git tag -a desktop-v0.1.0 -m "Desktop 0.1.0"
git push origin desktop-v0.1.0

# 方式 2：网页 Run workflow
# https://github.com/ChinaCarlos/fund-helper/actions/workflows/desktop-release.yml

# 方式 3：脚本（需 gh login）
chmod +x publish-desktop.sh
./publish-desktop.sh 0.1.0 --release

构建完成后执行 ./publish-desktop.sh 0.1.0 --collect 可将产物拉到本地 assets/releases/。

详见 assets/releases/README.md。

#技术栈

#环境要求

本地开发

• Python 3.11+（推荐 3.12）
• uv
• Node.js 18+
• pnpm 9+（各子项目统一 pnpm workspace 管理；项目根 .npmrc 使用国内镜像，不影响系统 registry）
• MongoDB 7+（本地 mongodb://localhost:27017，或通过 Docker 仅启动 mongo 服务）

Docker 部署

• Docker 24+
• docker compose v2+

#部署模式

MongoDB 打包在项目 Docker 配置里，无需本机单独安装数据库。

两套数据完全隔离，可同时运行（:8080 Docker 应用 + :3000 本地前端各用各库）。

#快速体验（拉取预构建镜像）

无需本地构建，直接使用 GitHub Container Registry 上的镜像：

git clone https://github.com/ChinaCarlos/fund-helper.git
cd fund-helper

# 拉取镜像并启动（app + MongoDB）
docker compose --profile full pull
docker compose --profile full up -d

# 查看状态
docker compose --profile full ps
docker compose --profile full logs -f app

浏览器打开 http://localhost:8080 ，使用默认管理员账号登录：

可通过环境变量 ADMIN_USERNAME / ADMIN_PASSWORD 修改（见 docker-compose.yml 或 .env.docker.example）。

登录后可访问市场排行等页面；持仓页需额外绑定养基宝（微信扫码，见首页提示）。

镜像为公开包时可直接拉取；若仓库设为私有，需先 docker login（Docker Hub 用户名 + Access Token）。

#维护者发布镜像

chmod +x publish-image.sh
docker login           # Docker Hub 用户名 + Access Token
./publish-image.sh     # 可选指定版本号: ./publish-image.sh v1.0.0

#Docker 一体部署（本地构建）

若需修改代码后自行构建镜像：

cd /path/to/fund-helper

docker compose --profile full up -d --build
docker compose --profile full ps
docker compose --profile full logs -f
docker compose --profile full down          # 停止（保留 mongo_data）
docker compose --profile full down -v       # 停止并清除部署库数据

访问 http://localhost:8080

• API 与页面由同一容器提供（SERVE_STATIC=true）
• MongoDB 数据持久化在 Docker 卷 mongo_data（与本地开发的 mongo_dev_data 隔离）
• 环境变量示例见 .env.docker.example

#本地开发（推荐：Docker 只跑 MongoDB）

请在系统终端 (Terminal.app / iTerm) 中操作，避免 Cursor 沙箱拦截养基宝 API。

cd /path/to/fund-helper

# 安装全部前端子项目依赖（使用项目内 .npmrc 镜像，不改系统 registry）
pnpm install

# 1. 启动开发 MongoDB（独立数据卷 mongo_dev_data）
./dev-infra.sh

# 2. 本机启动前后端（会自动连 localhost:27017）
./start.sh

• 后端：http://localhost:8000
• 前端：http://localhost:3000（`web/`）
• 数据库：容器 fund-helper-mongo-dev，卷 mongo_dev_data

本地环境变量示例见 backend/.env.example（复制为 backend/.env 可选）。

#全新安装

./reset.sh
./dev-infra.sh
./start.sh

#修改代码后重启

# Ctrl+C 停止后
./start.sh

#功能

#持仓监控（/）

• 账号密码登录（无自助注册）：首次启动自动创建管理员 admin / 123456（可配置）
• 管理员可在「用户管理」添加 / 编辑 / 删除用户
• 养基宝绑定：持仓数据需微信扫码绑定养基宝；未绑定或 Token 过期时展示绑定二维码
• 多用户隔离：Session Cookie + MongoDB，通知配置按 user_id 存储
• 手动刷新拉取养基宝持仓：大盘指数、汇总卡片、多账户 Tab
• 分组收益曲线（SVG 自研图表）、基金搜索 / 添加 / 删除
• 基金表格列可自定义显示

#市场数据

• 市场排行（/market）：全市场基金多维度排行，列配置、基金收益曲线弹窗
• 板块热力图（/market/heatmap）：行业/概念板块涨幅或资金流向，下钻板块关联基金

#通知推送（设置页）

• 支持钉钉、飞书、企业微信（Webhook 群机器人或企业应用）
• 触发策略：手动刷新后 / 每 1~60 分钟 / 仅交易时段
• 配置持久化到 MongoDB notification_configs（按用户 user_id）

#部署

• 本地开发：前后端分离（:8000 + :3000）
• Docker：单容器 :8080，API 与页面同域

#浏览器插件（chrome-extension/）

• Chrome / Edge / 360 极速（Chromium 内核）：加载 dist/ 即可使用
• 微信扫码登录养基宝，登录态保存在 chrome.storage.local
• 四大指数、总资产、当日收益、涨跌分布、多账户 Tab
• 基金列表排序：当日涨幅（交易时段为预估涨幅）/ 当日收益 / 持仓余额，支持正序与倒序
• 直连养基宝 API，不依赖 fund-helper 后端与 MongoDB

安装与开发见 chrome-extension/README.md。

#VS Code / Cursor 扩展（vscode-extension/）

• 在 VS Code、Cursor、Trae、CodeBuddy、Qoder 等编辑器内查看养基宝持仓，UI 与浏览器插件对齐
• 四个入口：活动栏图标、状态栏、底部 Panel Tab、编辑器标题栏（见 入口示意图）
• 微信扫码登录；登录态保存在扩展 globalState
• 样式适配编辑器明暗主题（--vscode-charts-red/green 等）
• 直连养基宝 API（经 Extension Host 代理），不依赖 fund-helper 后端与 MongoDB

安装：

| Cursor / Trae / CodeBuddy / Qoder | VSIX 文件 | 下载 VSIX |

Release 页：vscode-v0.1.4 · 文件 fund-helper-vscode-0.1.4.vsix

非 VS Code 编辑器：Cmd+Shift+P → Extensions: Install from VSIX… → 选择下载的 .vsix → 重载窗口。

详见 vscode-extension/README.md；架构见 TECH.md §19。

#JetBrains IDE 插件（jetbrains-extension/）

• 在 IntelliJ IDEA、WebStorm、PyCharm、GoLand 等 IDE 内查看养基宝持仓，UI 与 VS Code 扩展同源（React + JCEF）
• 左侧 Tool Window：登录 + 持仓主界面
• 状态栏（右下角）：显示当日收益与涨幅；点击打开底部 Fund Helper Panel
• 底部 Tool Window：默认隐藏，由状态栏唤起；关闭后可再次点击状态栏打开
• 背景与文字跟随 IDE 主题（LaF 注入）；涨跌数字固定红涨绿跌
• 直连养基宝 API（Kotlin 插件进程代理），不依赖 fund-helper 后端与 MongoDB

安装：

| IntelliJ IDEA / WebStorm / PyCharm 等 | 插件 zip | 下载 zip |

Release 页：jetbrains-v0.1.1 · 文件 fund-helper-jetbrains-0.1.1.zip

Settings → Plugins → ⚙ → Install Plugin from Disk… → 选择 zip → 重启 IDE。

环境要求：IDE 2024.2+（build 242+），需支持 JCEF。

详见 jetbrains-extension/README.md；架构见 TECH.md §20。

#桌面端（desktop/）

• macOS / Windows 原生客户端（Tauri v2 + Rust），无需部署后端
• 微信扫码登录养基宝；登录态与通知配置均存本地 SQLite
• 持仓：大盘指数、汇总卡片、多账户 Tab、基金排序、分组收益曲线（SVG）
• 消息通知：钉钉 / 飞书 / 企业微信（Webhook 或飞书应用 IM 卡片），手动刷新 / 定时推送
• 浅色 / 深色主题、系统托盘、单实例

开发与打包见 desktop/README.md；安装包见上文 桌面端下载。

#目录结构

fund-helper/
├── Dockerfile
├── docker-compose.yml      # mongo（开发/部署共用）+ app（一体部署）
├── dev-infra.sh            # 本地开发：仅启动 MongoDB
├── reset.sh
├── start.sh
├── backend/
├── web/                    # Web 应用（React SPA）
├── chrome-extension/       # 浏览器插件（CRXJS + React Popup）
├── vscode-extension/       # VS Code / Cursor 扩展（Webview + Extension Host）
├── jetbrains-extension/    # JetBrains IDE 插件（JCEF + Kotlin）
├── desktop/                # 桌面端（Tauri + Rust）
├── docs-site/              # 文档中心（Rspress → GitHub Pages）
├── assets/releases/        # 客户端安装包（本地构建或 CI collect）
├── publish-chrome.sh       # Chrome 发版脚本
├── publish-vscode.sh       # VS Code 扩展发版脚本
├── publish-jetbrains.sh    # JetBrains 插件发版脚本
├── publish-desktop.sh      # 桌面端发包脚本
├── publish-image.sh        # Docker 镜像发布脚本
├── TECH.md
└── API_README.md           # 养基宝上游 API

#页面路由

#API 速查

#认证与持仓

#市场数据

#通知

详见 TECH.md。

#常见问题

#ServerSelectionTimeoutError: mongo:27017 Name or service not known

mongodb://mongo:27017 仅用于 Docker 内的 app 容器。本机 ./start.sh 请使用 mongodb://localhost:27017，并先执行 ./dev-infra.sh。

#Docker 容器无法启动

检查 docker compose logs，常见为环境变量格式问题。CORS_ORIGINS 支持逗号分隔。

#Blocked by sandbox network policy

请改用系统终端执行 ./start.sh 或 docker compose up。

#想完全重来

./reset.sh && ./start.sh
# 或 Docker
docker compose --profile dev --profile full down -v
docker compose --profile full up -d --build

#浏览器插件无法加载或接口失败

• 确认使用 Chrome / Edge / 360 极速（Chromium 内核） 加载 chrome-extension/dist/
• 开发模式：cd chrome-extension && pnpm install && pnpm dev，在扩展管理页选择 dist/ 目录
• 插件直连养基宝，与 Web 应用后端无关；401 时重新扫码登录即可
• Firefox 暂未专门适配，见 chrome-extension/README.md