rodriguestiago0/actual-mealcards

Meal cards - actual 镜像文档

镜像概述和主要用途

Meal cards - actual 是一款用于将My Edenred和Coverflex预付卡交易导入到Actual预算应用的工具。它支持通过配置用户凭证和导入频率，自动同步卡交易至Actual，减少手动录入工作，适用于使用上述预付卡并通过Actual进行财务管理的用户。

核心功能和特性

• 多提供商支持：兼容My Edenred和Coverflex两种预付卡服务
• 交易导入：将预付卡交易数据同步至Actual预算应用
• 定时同步：通过CRON表达式自定义导入频率
• 多账户管理：支持配置多个预付卡账户及其在Actual中的对应映射
• 灵活部署：可通过Docker容器化部署或手动运行

使用场景和适用范围

适用于使用My Edenred或Coverflex预付卡，且通过Actual预算应用进行个人或家庭财务管理的用户。尤其适合需要定期同步卡交易记录，避免手动录入交易明细的场景。

使用方法和配置说明

前置要求

• Actual预算应用账户及服务器信息（URL、密码、Sync ID）
• My Edenred或Coverflex的用户凭证
• Docker环境（推荐，用于容器化部署）或Node.js环境（手动运行）

获取必要参数

My Edenred

• User ID：格式为GUID（非***），iOS用户可通过Proxyman应用抓取请求获取；PIN为My Edenred应用的PIN码
• 注意：待处理交易将作为已结算交易导入，若后续交易被删除，需在Actual中手动删除

Coverflex

• User Agent Token：通过浏览器网络标签页获取，搜索请求https://menhir-api.coverflex.com/api/employee/movements?，其中的pocket_id需作为COVERFLEX_ACCOUNT配置

环境变量配置

部署方式

Docker Compose部署

创建docker-compose.yaml文件：

yaml
version: '3'
services:
  actual_mealcards:
    container_name: actual_mealcards
    image: docker.xuanyuan.run/rodriguestiago0/actual_mealcards
    environment:
      - PUID=1003
      - PGID=100
      - TZ=Europe/Lisbon  # 替换为实际时区
      - EDENRED_USERNAME=  # 替换为My Edenred用户名
      - EDENRED_PIN=       # 替换为My Edenred PIN码
      - EDENRED_VERSION=4.1.0  # 可选，默认4.1.0
      - EDENRED_ACCOUNT=   # 替换为My Edenred账户标识
      - EDENRED_ACTUAL_ACCOUNT=  # 替换为Actual对应账户名
      - EDENRED_ACCOUNT_1=  # 可选，额外账户标识
      - EDENRED_ACTUAL_ACCOUNT_1=  # 可选，额外账户映射
      - ACTUAL_SERVER_URL=  # 替换为Actual服务器URL
      - ACTUAL_SERVER_PASSWORD=  # 替换为Actual服务器密码
      - ACTUAL_SYNC_ID=  # 替换为Actual Sync ID
      - CRON_EXPRESSION=0 */4 * * *  # 可选，同步频率
      - COVERFLEX_USERNAME=  # 替换为Coverflex用户名
      - COVERFLEX_PASSWORD=  # 替换为Coverflex密码
      - COVERFLEX_USER_AGENT_TOKEN=  # 替换为User Agent Token
      - COVERFLEX_IMPORT_FROM=  # 可选，导入起始日期
      - COVERFLEX_ACCOUNT=  # 替换为pocket_id
      - COVERFLEX_ACTUAL_ACCOUNT=  # 替换为Actual对应账户名
      - COVERFLEX_ACCOUNT_1=  # 可选，额外账户标识
      - COVERFLEX_ACTUAL_ACCOUNT_1=  # 可选，额外账户映射
    restart: unless-stopped

启动容器：docker compose up -d

Docker Run部署

bash
docker run -d --name actual_mealcards \
    -e PUID=1003 \
    -e PGID=100 \
    -e TZ=Europe/Lisbon \
    -e EDENRED_USERNAME=your_edenred_username \
    -e EDENRED_PIN=your_edenred_pin \
    -e EDENRED_VERSION=4.1.0 \
    -e EDENRED_ACCOUNT=your_edenred_account \
    -e EDENRED_ACTUAL_ACCOUNT=actual_edenred_account \
    -e EDENRED_ACCOUNT_1=optional_second_edenred_account \
    -e EDENRED_ACTUAL_ACCOUNT_1=optional_second_actual_account \
    -e ACTUAL_SERVER_URL=https://your-actual-server.com \
    -e ACTUAL_SERVER_PASSWORD=your_actual_password \
    -e ACTUAL_SYNC_ID=your_actual_sync_id \
    -e CRON_EXPRESSION="0 */4 * * *" \
    -e COVERFLEX_USERNAME=your_coverflex_username \
    -e COVERFLEX_PASSWORD=your_coverflex_password \
    -e COVERFLEX_USER_AGENT_TOKEN=your_coverflex_token \
    -e COVERFLEX_IMPORT_FROM=2024-01-01 \
    -e COVERFLEX_ACCOUNT=your_coverflex_pocket_id \
    -e COVERFLEX_ACTUAL_ACCOUNT=actual_coverflex_account \
    -e COVERFLEX_ACCOUNT_1=optional_second_coverflex_account \
    -e COVERFLEX_ACTUAL_ACCOUNT_1=optional_second_actual_coverflex_account \
    --restart=unless-stopped docker.xuanyuan.run/rodriguestiago0/actual_mealcards:latest

手动运行（非容器化）

1. 克隆仓库（需替换为实际仓库地址）
2. 安装依赖：npm ci
3. 复制环境变量模板：cp .sample.env .env，并编辑.env填写参数
4. 运行导入命令：
   • My Edenred：node index.js import-myendenred
   • Coverflex：node index.js import-coverflex

命令说明

  Usage
    $ mealcards <command> <flags>

  Commands & Options
    import-myendenred   将My Edenred账户同步到Actual预算
    import-coverflex    将Coverflex账户同步到Actual预算
    config              打印配置文件位置

  Examples
    $ mealcards import-myendenred

注意事项

• 初始余额：首次导入无起始余额，需在Actual中手动添加
• 账户创建：需在Actual中手动创建账户，并确保与配置的EDENRED_ACTUAL_ACCOUNT/COVERFLEX_ACTUAL_ACCOUNT对应
• My Edenred交易删除：待处理交易导入后若被删除，需在Actual中手动删除对应记录