境外资本利得税计算工具

计算中国大陆税务居民境外证券投资所得的个人所得税。支持富途(港股)和老虎(美股/港股)两个券商的年度账单自动解析。

功能概述

• 自动解析富途 Excel 年度账单（股票交易、期权交易、分红）
• 自动解析老虎 PDF 年度账单（期权、股票、行权、分红）
• 加权平均成本法计算已实现资本利得
• 自动处理期初持仓的成本继承
• 分国家/地区计算应纳税额（方案A：分国别 / 方案B：合并盈亏）
• 境外已缴税款抵扣计算
• 生成结构化税务报告

支持的市场

券商	市场	币种	品种
富途	港股	HKD	股票、期权
老虎	港股	HKD	股票、期权、行权
老虎	美股	USD	股票、期权、行权

暂不支持 A 股、新加坡、日本等其他市场。如需扩展，需添加对应的汇率和解析逻辑。

快速开始

# 安装依赖
pip install -r requirements.txt

# 将券商年度账单放入同目录（或指定路径）
# 富途: 2025-年度账单-futu.xlsx
# 老虎: 2025-年度账单-tiger.pdf

# 运行（年度为必填参数）
python tax_calculator.py 2025

# 指定自定义文件路径
python tax_calculator.py 2025 --futu path/to/futu.xlsx --tiger path/to/tiger.pdf

每年使用流程

年度 Checklist

1. 下载账单

   • 富途：App → 账户 → 全部 → 我的税表（账户栏目）→ 年份选择（例如：2025）→ 年度账单.xlsx
   • 老虎：App → 我的 → 老虎账户 → 账单报表 → 账单报表 → 自定义 → 选择账单时间（例如：2025/01/01 至 2025/12/31）

2. 放置文件

   • 命名为 <year>-年度账单-futu.xlsx 和 <year>-年度账单-tiger.pdf
   • 或使用 --futu / --tiger 参数指定路径

3. 更新汇率（如需要）

   • 查询当年人民银行年度平均中间价
   • 通过 --usd-rate / --hkd-rate 参数或环境变量设置

4. 核实期初持仓成本

   • 如有跨年持仓，检查 INITIAL_COSTS 配置
   • 确认是否需要覆盖默认的期初市值

5. 运行并检查报告

   python tax_calculator.py <YEAR>

6. 在个人所得税 App 中申报

   • 报告保存在 output/tax_report_<year>.txt，对照"个税App申报填写参考"section 填写
   • 路径：首页 → 综合所得年度汇算 → 标准申报 → 更正申报
   • 填写栏位对应：

   App 字段	报告中对应值	说明
   利息、股息、红利所得 → 应纳税所得额	分红总额(CNY)	不扣除已缴税，填总额
   财产转让所得 → 应纳税所得额	资本利得(CNY)	方案A或方案B的值
   境外所得境内支付部分已缴税额	H股代扣税(CNY)	H股分红10%代扣
   境外所得境外支付部分预缴税额	美股预扣税(CNY)	美国股息预扣税
   境外已缴税额可抵免额 → 步骤一	按国家填写明细	点进后添加"美国"条目

数据准备要求

富途 Excel 格式

需要包含以下 Sheet：

Sheet 名	用途
证券-交易流水	股票和期权买卖记录
证券-资金进出	分红收入和相关费用
证券-持仓总览	期初/期末持仓

老虎 PDF 格式

PDF 中需包含以下 Section（按标题行识别）：

• 期权（交易明细和合计行）
• 股票（交易明细和合计行）
• 合约行权/过期
• 股息

注意：如果老虎修改了 PDF 排版，程序会输出警告。此时需要对照 PDF 核实数据。

配置项说明

命令行参数

参数	说明	默认值
year (必填)	税务年度	无
--futu FILE	富途账单路径	<year>-年度账单-futu.xlsx
--tiger FILE	老虎账单路径	<year>-年度账单-tiger.pdf
--usd-rate	USD/CNY 汇率	7.1886
--hkd-rate	HKD/CNY 汇率	0.9243
--output-dir	输出目录	./output

环境变量

变量	说明
EXCHANGE_RATE_USD	USD/CNY 汇率
EXCHANGE_RATE_HKD	HKD/CNY 汇率

优先级：CLI 参数 > 环境变量 > 代码默认值

期初持仓成本

编辑 tax_calculator.py 中的 INITIAL_COSTS 字典：

INITIAL_COSTS = {
    "6099": 28800.00,          # 格式1: 代码 → 总成本(HKD)
    "2459": (4000, 808.00),    # 格式2: 代码 → (数量, 总成本)
}

如不设置，默认使用期初持仓市值（数量 × 期初价格）作为成本。

输出报告解读

报告分为四个部分：

一、富途证券账户

• 股票已实现损益（加权平均成本法逐笔计算）
• 期权已实现损益（按标的资产分组）
• 股息/分红收入（扣除相关费用后净额）

二、老虎证券账户

• 港股部分（HKD）：期权交易、行权/过期、股票
• 美股部分（USD）：期权交易、行权/过期、股票
• 分红（含境外预扣税明细）

三、应纳税额计算

• 方案A（分国别）：港股和美股分别计算，亏损不跨区抵消
• 方案B（合并）：所有地区盈亏合并后计算
• 已缴税款抵扣：境外预扣税 + H股已缴国内税

四、重要说明

• 免责声明及注意事项

税务规则速查

规则	说明
税率	20%（财产转让所得 / 股息红利所得）
成本计算	加权平均法（分批买入同一股票）
盈亏抵消	同一国家/地区内可抵消；跨国需分别计算
境外税收抵免	实际可抵 = min(已缴境外税, 该国来源所得 × 20%)
H股分红税	10% 由企业代扣代缴（属国内已缴税款）
汇率	按年度平均汇率折算（中国人民银行中间价）
货币基金	是否申报存在争议，本工具暂不计入
申报期	次年 3 月 1 日 – 6 月 30 日

项目结构

make-tax/
├── tax_calculator.py        # 主程序
├── requirements.txt         # Python 依赖
├── README.md                # 本文件
├── .gitignore               # Git 忽略规则（数据文件不入库）
├── <year>-年度账单-futu.xlsx # 富途数据（用户提供，git 忽略）
├── <year>-年度账单-tiger.pdf # 老虎数据（用户提供，git 忽略）
└── output/
    └── tax_report_<year>.txt # 生成的报告（git 忽略）

常见问题

Q: 运行报错 "文件不存在" A: 检查文件名是否匹配 <year>-年度账单-futu.xlsx / <year>-年度账单-tiger.pdf 格式，或使用 --futu / --tiger 参数显式指定。

Q: 老虎解析结果全为零 A: 老虎可能修改了 PDF 格式。请对照 PDF 核实各 section 的合计行格式，必要时调整解析逻辑。

Q: 期初持仓成本不对 A: 默认使用上年末市值。如需精确计算，在 INITIAL_COSTS 中填入实际买入成本。

Q: 方案A和方案B选哪个？ A: 方案A更符合税法字面规定（分国不分项），方案B在部分地区实务中被接受。建议咨询当地税务机关或税务顾问。

Q: 新增了一个券商怎么办？ A: 需编写对应的解析函数并将结果接入 calculate_tax() 中。参考 parse_futu_trades() 或 parse_tiger_pdf() 的接口模式。

Q: 换年度使用需要改代码吗？ A: 不需要。只需 python tax_calculator.py 2026，并提供对应年度的账单文件和汇率。