{"id":13648121,"url":"https://github.com/jiegec/china_bean_importers","last_synced_at":"2025-04-06T07:09:56.840Z","repository":{"id":68569541,"uuid":"595887554","full_name":"jiegec/china_bean_importers","owner":"jiegec","description":"Beancount importers for Chinese users","archived":false,"fork":false,"pushed_at":"2025-03-09T07:52:08.000Z","size":173,"stargazers_count":87,"open_issues_count":2,"forks_count":18,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-30T06:03:58.633Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jiegec.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-01T02:18:23.000Z","updated_at":"2025-03-29T07:51:02.000Z","dependencies_parsed_at":"2023-10-03T15:13:53.111Z","dependency_job_id":"3d60356f-6055-451b-8934-8d89ef74f36f","html_url":"https://github.com/jiegec/china_bean_importers","commit_stats":{"total_commits":101,"total_committers":9,"mean_commits":"11.222222222222221","dds":0.5841584158415842,"last_synced_commit":"94ca18258720f0ccb8580b76a185f4e3e003a002"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiegec%2Fchina_bean_importers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiegec%2Fchina_bean_importers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiegec%2Fchina_bean_importers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiegec%2Fchina_bean_importers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jiegec","download_url":"https://codeload.github.com/jiegec/china_bean_importers/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247445667,"owners_count":20939958,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T01:03:59.160Z","updated_at":"2025-04-06T07:09:56.831Z","avatar_url":"https://github.com/jiegec.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# china_bean_importers\n\n[![Test Python package](https://github.com/jiegec/china_bean_importers/actions/workflows/test_package.yml/badge.svg)](https://github.com/jiegec/china_bean_importers/actions/workflows/test_package.yml)\n\n[![PyPI](https://badge.fury.io/py/china-bean-importers.svg)](https://pypi.org/project/china-bean-importers/)\n\nBeancount 导入脚本，支持的数据源包括：\n\n- 微信支付\n- 支付宝（网页端、手机端）\n- 中国银行信用卡、借记卡\n- 招商银行借记卡\n- 建设银行借记卡\n- 民生银行借记卡、信用卡\n- 工商银行借记卡（测试）\n- 清华大学校园卡（新、旧）\n- 汇丰香港信用卡、储蓄账户\n\n**说明：本项目尚不支持 Beancount 3 或更新的版本。**\n\n## 使用方法\n\n使用 pypi 安装：\n\n```shell\npip3 install china-bean-importers\n```\n\n或者克隆本仓库或作为 submodule：\n\n```shell\ngit clone https://github.com/jiegec/china_bean_importers\n# or\ngit submodule add git@github.com:jiegec/china_bean_importers.git\n```\n\n然后安装 importer 和依赖：\n\n```shell\ncd china_bean_importers\npip install --editable .\n```\n\n运行 `cp config.example.py config.py` 复制配置模板，编辑 `config.py` 填入你的配置，**放置在你的项目目录中**。\n\n最后，在 beancount 使用的导入脚本中按需加入：\n\n```python\nfrom china_bean_importers import wechat, alipay_web, alipay_mobile, boc_credit_card, boc_debit_card, cmb_debit_card\n\nfrom china_bean_importer_config import config # your config file name\n\nCONFIG = [\n    wechat.Importer(config),\n    alipay_web.Importer(config),\n    alipay_mobile.Importer(config),\n    boc_credit_card.Importer(config),\n    boc_debit_card.Importer(config),\n    cmb_debit_card.Importer(config),\n]\n```\n\n## Importer 配置\n\n上面的例子中，每个 Importer 都由全局配置控制行为，格式如 `config.example.py` 所示。其中部分字段的含义包括：\n\n- `importers`：每个 importer 各自需要的配置，通常包括账户映射、分类映射等。其中 `card_narration_whitelist` 和 `card_narration_blacklist` 两个字段适用于各类信用卡 Importer，用于过滤可能在其他 importer 中出现的交易描述（通常是通过支付软件产生的交易）。\n- `card_accounts`：记录各类卡账户的最后四位数字，以自动化地进行账户匹配。如有重复，则默认使用第一个找到的。\n- `pdf_passwords`：在 importer 遇到加密的 PDF 时，会自动尝试这些密码进行解密。推荐使用工具去除密码，避免后续的麻烦。\n- `unknown_expense/income_account`：无法匹配情况下使用的支出/收入账户。\n- `detail_mapping`：用于从交易描述、对手等信息中匹配目标账户、标签等信息，是一个 `BillDetailMapping` 的列表，每个 `BDM` 包含字段：\n  - `narration_keywords`：用于匹配交易描述\n  - `payee_keywords`：用于匹配交易对手，可以使用 `SAME_AS_NARRATION` 来表示与交易描述使用的关键词一致\n  - `destination_account`：在匹配时，对账目使用的目标账户\n  - `additional_tags/metadata`：在匹配时，在账目上添加的额外标签和元数据\n  - `priority`：默认为 0，值越大则优先级越高\n  - `match_logic`：默认为 `\"OR\"`，即交易描述或交易对手任意一个匹配即可；可以设置为 `\"AND\"`，即交易描述和交易对手都需要匹配\n\n## 可用 Importer\n\n### 微信支付（`wechat`）\n\n导出方法：我的-\u003e支付-\u003e钱包-\u003e账单-\u003e常见问题-\u003e下载账单-\u003e用于个人对账\n\n下载邮件附件，解压得到 csv 文件，如：\n\n```csv\n微信支付账单明细,,,,,,,,\n微信昵称：[123412341234],,,,,,,,\n起始时间：[2022-11-01 00:00:00] 终止时间：[2023-02-01 00:00:00],,,,,,,,\n```\n\n### 支付宝（网页端）（`alipay_web`）\n\n导出方法：访问支付宝官网-\u003e登录-\u003e查看所有交易记录-\u003e筛选-\u003e下载 Txt 格式账单\n\n下载后，解压得到 txt 文件，如：\n\n```csv\n支付宝交易记录明细查询\n账号:[123412341234]\n起始日期:[2023-01-26 00:00:00]    终止日期:[2023-02-01 00:00:00]\n```\n\n但支付宝网页端导出的数据并没有记录付款账户，因此不适合 beancount，**不推荐使用**。\n\n### 支付宝（手机端）（`alipay_mobile`）\n\n导出方法：我的-\u003e账单-\u003e...-\u003e开具交易流水证明-\u003e用于个人对账-\u003e申请\n\n下载邮件附件，解压得到 csv 文件，如：\n\n```csv\n------------------------支付宝（中国）网络技术有限公司  电子客户回单------------------------\n收/支                 ,交易对方                ,对方账号                ,商品说明                ,收/付款方式              ,金额                  ,交易状态                ,交易分类                ,交易订单号     ,商家订单号           ,交易时间            ,\n```\n\n### 中国银行信用卡（`boc_credit_card`）\n\n每个月中行会发送信用卡合并账单，下载邮件附件 PDF；或者在中国银行手机客户端-信用卡-历史账单-选择月份-发送电子账单，从邮箱保存，获得 EML 格式的文件。\n\nImporter 可自动识别上述两种格式。\n\n### 中国银行借记卡（`boc_debit_card`）\n\n在中国银行手机客户端，点击更多-\u003e助手-\u003e交易流水打印-\u003e立即申请，记录下 PDF 密码。\n\n下载邮件附件，得到带有密码的 PDF 文件，把密码记录到 `config.py` 中，或者使用工具去除密码。\n\n### 中国建设银行借记卡（`ccb_debit_card`）\n\n手机客户端导出方法：我的-\u003e银行卡-\u003e管理-\u003e明细导出-\u003e明细导出申请-\u003e选择发送方式为 Excel。申请成功后，查询导出历史，得到解压密码。\n\n下载邮件附件，输入密码解压 ZIP 文件，得到 XLS，转换为 CSV 格式。\n\n### 招商银行借记卡（`cmb_debit_card`）\n\n在手机银行客户端，点击首页-\u003e流水打印-\u003e高级筛选-\u003e显示完整卡号-\u003e显示收入及支出汇总金额-\u003e同意协议并提交，记录下解压密码。\n\n下载邮件附件，输入密码解压 ZIP 文件，得到 PDF。\n\n### 民生银行借记卡（`cmbc_debit_card`）\n\n在手机银行客户端，点击收支明细-\u003e（右上角菜单）交易明细-\u003e导出（下载电子版明细）-\u003e交易类型全部-\u003e排版方式横版-\u003e同意协议并提交。\n\n下载邮件附件，解压 ZIP 文件，得到 PDF。\n\n### 民生银行信用卡（`cmbc_crebit_card`）\n\nImporter 支持以下两种格式：\n\n1. 民生银行发送至邮箱的电子账单 EML 文件（**推荐**，可自动识别货币）。\n\n2. 手动将查询（[民生银行信用卡](https://creditcard.cmbc.com.cn/home/cn/web/product/index.shtml)-登录-账单查询）的账单转换为 CSV 文件，格式为（带表头，注意各列顺序）：\n\n```csv\n交易日,记账日,卡号末四位,授权码,金额,摘要\n0104,20230104,XXXX,,-88.88,foo-bar\n```\n\n注意此方法默认所有交易货币均为 CNY。\n\n### 汇丰银行（香港）（`hsbc_hk`）\n\n支持汇丰香港储蓄账户/信用卡账单，感谢 [ckyOL](https://blog.ckyol.moe/2023/11/24/HSBCHKcreditCSVImporter/) 提供的经验。\n\n导出方式：登录汇丰网银，点击账户到交易记录页，设定筛选日期进行搜索（信用卡可选择“当期账单”），点击底部下载按钮得到 CSV 文件。导出的文件名必须以 `ACC_` 开头，其中 `ACC` 用于映射不同的账户，需要在 `account_mapping` 配置中存在：\n\n```python\n'hsbc_hk': {\n    \"account_mapping\": {\n        \"One\": \"Assets:Bank:HSBC\",\n        \"PULSE\": \"Liabilities:CreditCards:HSBC:Pulse\"\n    },\n}\n```\n\n如果在配置中设置 `use_cnh` 为 `True`，则所有人民币的货币符号将记为 CNH，否则默认记为 CNY。\n\n### 清华大学校园卡（旧）（`thu_ecard_old`）\n\n导出方式：校园网环境登录 \u003cecard.tsinghua.edu.cn\u003e，交易日志查询-\u003e导出，并使用 Excel 转存为 CSV 格式。\n\n注意：导出总是包含入学以来所有记录，可根据需要删除此前已经导入的内容。\n\n### 清华大学校园卡（新）（`thu_ecard`）\n\n由于校园卡系统与浏览器交互的数据进行了一定的“加密”（并无实际意义），原始数据的获取需要按照以下步骤进行：\n\n1. 使用统一身份认证登录 card.tsinghua.edu.cn\n2. 按 F12 打开浏览器工具，复制 `thu_ecard/decode.js` 的代码，粘贴到控制台中。修改必要的参数：`idserial` 改为本人学工号，`starttime` 和 `endtime` 改为需要的日期范围（闭区间）。然后执行。\n3. 将控制台中打印的 JSON 转换为 CSV 格式存储（可使用在线工具 [1](https://data.page/json/csv)、[2](https://www.convertcsv.com/json-to-csv.htm)、[3](https://konklone.io/json/)，或使用 Pandas 等库）。\n\n## 测试 Importer\n\n### 微众银行借记卡（尚未实现）\n\n手机客户端导出方法：左上角菜单-\u003e证明开具-\u003e微众卡交易流水。\n\n下载邮件附件，输入密码解压 ZIP 文件，得到 PDF。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjiegec%2Fchina_bean_importers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjiegec%2Fchina_bean_importers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjiegec%2Fchina_bean_importers/lists"}