本地解析期货结算单与保证金监控中心日报，生成账户复盘报告的 Web 工具。本项目不连接交易柜台，不下单，也不提供交易信号。
本项目以公开可见源码、受限授权的方式发布。它不是 OSI 定义的开源软件，也不建议发布到 PyPI；使用和再分发前请先阅读 LICENSE。
重要使用边界
- 本项目仅用于本地数据整理、历史统计与个人复盘，不构成投资建议、交易建议、法律意见、税务意见、会计意见或任何收益承诺。
- 自动解析、分类、脱敏、交易日识别和收益归因都可能出错或不完整。任何报告均应与原始结算单、期货公司记录及其它权威资料人工核对，不得直接作为下单、风控、估值、审计、报税、客户披露或争议处理的唯一依据。
- 期货及期权交易具有杠杆和损失风险。历史统计、回测结果和风险指标不代表未来表现。
- 你必须对数据来源、访问权限、处理目的、保存期限、报告分享和实际使用后果自行负责。不同地区及不同身份适用的法律、监管规则和合同义务可能不同。
支持输入：
- 期货公司
txt结算单 - 压缩包
zip - 保证金监控中心
xls/xlsx - 含上述文件的目录
输出结果：
- HTML 报告，文件名形如
settlement_report_YYYYMMDD.html - PDF 报告，文件名形如
settlement_report_YYYYMMDD.pdf - 每日净值 Excel，文件名形如
daily_nav_YYYYMMDD.xlsx - CSV 明细，文件名会带生成当天日期后缀
- 账户权益、单位净值、份额、份额变动、累计净利润
- 出入金明细、分类汇总、备注脱敏
- 期货与期权分开统计的分品种结算贡献与净盈利
- 保证金监控中心下载目录生成前完整性校验、缺失补下载与重复日报清理
- 报告页下载每日净值 Excel，默认文件为
daily_nav_YYYYMMDD.xlsx；出入金发生明细支持按银期转账、手续费返佣、返息、其他筛选并下载当前筛选明细 Excel - 风险暴露、每周/每月盈亏、隔夜净暴露图
- 交易行为统计：平仓胜率、盈亏比、平均持仓天数
- 持仓周期分桶统计：胜率、总平仓盈亏、平均单笔平仓盈亏
本项目的许可范围以根目录 LICENSE 为准。若你不同意或无法遵守其中的条件，请勿下载、复制、运行、修改或分发本项目。以下仅为便于阅读的摘要；如与 LICENSE 不一致，以 LICENSE 为准：
- 仅可用于处理你本人拥有，或你已取得明确合法授权的数据
- 禁止未经授权批量分析、整理、归档或传播第三方结算单
- 禁止用于收费服务、商业产品、SaaS、代运营、咨询交付或其它直接/间接盈利场景
- 禁止将本项目作为自动化抓取、绕过平台限制或规避访问控制的工具使用
- 禁止去除、隐藏或篡改本项目中的风险提示、免责声明与授权说明
如果你的使用场景涉及团队内部共享、对外服务、客户交付或系统集成，应先取得权利人书面授权。
将仓库设为 GitHub Public，会依照 GitHub 服务条款允许其他 GitHub 用户通过平台功能查看和 fork 仓库。公开可见或可 fork 不等于取得开源、商用、再许可、对外服务或其它超出 LICENSE 的权利；适用法律另有规定的除外。
公开仓库可能被搜索引擎、归档服务或第三方长期缓存。发布者不应向仓库、Issue、Discussion、Pull Request、日志或截图提交任何真实结算单、账号、Cookie、token、内部路径或其它敏感资料。
需要 Python 3.11+（推荐 64 位）以及 Google Chrome 或 Chromium。Linux、Windows 的完整步骤与故障排查见 INSTALL.md。
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install .
futures-settlements-cnpy -3 -m venv .venv
Set-ExecutionPolicy -Scope Process Bypass
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install .
futures-settlements-cn构建产物只包含源码和文档，不应包含任何结算单或报告：
python -m pip install build
python -m build生成的 dist/*.whl 与 dist/*.tar.gz 可用于你获授权的环境。
安装完成后，直接启动本地 Web 前端：
futures-settlements-cn也可以使用：
python -m futures_settlements_cn启动后：
- 以启动日志输出的本地地址为准，在浏览器打开页面
- 选择“本地目录”或“保证金监控中心”
- 填写日期范围、输出目录、报告标题
- 生成报告并查看 HTML
- 需要分享时，再从报告页导出 PDF
未填写输出目录时，程序会在启动命令所在目录下创建 reports/；请在你有写权限且便于保护数据的目录中启动。
- 在保证金监控中心工作区生成报告前，程序会识别同一交易日的重复
xls/xlsx，保留评分较高的一份并删除其余重复文件。请使用专用工作目录，并在首次处理重要数据前自行备份。 - 同一天在同一输出目录重复生成报告时，部分同名输出文件可能被覆盖。不要把唯一原件放在输出目录中。
- 程序不会替你建立备份、保留策略或访问控制。输入、下载和报告目录的权限、加密、备份与清理均由使用者负责。
- 支持
txt、zip、xls/xlsx和目录 - 目录会递归读取可解析文件
- 默认日期范围为近 3 个月
- 可手动改为任意更早的历史范围
- 只支持近一年日期范围
- 登录、验证码和可能的二次校验，需要用户在官方页面手动完成
- 工具不接收、不保存账号密码等凭据
- 每个新会话工作区只保存最小连接状态
.cfmmc_session.json，内容仅包括专用 Chrome 调试端口和启动时间，不包含账号密码、Cookie 或页面内容 - 本地后端意外退出后，只要原专用 Chrome 仍在运行，重新启动程序会自动扫描默认
reports目录中最近 20 个工作区并恢复会话；点击“创建或恢复登录会话”也会优先复用可用会话，恢复后可继续批量下载 - Linux 下由旧版本创建、没有状态文件的工作区，也会尝试从仍在运行的专用 Chrome 启动参数恢复；若专用 Chrome 已关闭或机器已重启，则仍需重新创建会话并手动登录
- 页面若提示本地服务连接失败，请重新运行启动程序并保持启动窗口开启；服务恢复后，页面会显示已恢复的监控中心会话状态
- 下载完成后可直接在同一页面生成报告
- 监控中心
xls/xlsx由 Python 包直接读取；Windows 机器不需要安装 LibreOffice，WPS/Excel 也只用于人工查看 - 低配机器建议一次处理不超过近一年窗口；程序读取
xlsx使用流式模式，且在生成报告前会先关闭本次专用 Chrome，避免浏览器和统计计算同时占用内存 - 生成报告前会扫描下载目录中的
xls/xlsx：- 预期交易日按“周一至周五”和
chinese-calendar.is_workday()的交集识别；不可用时退化为周一至周五 2024-02-09虽然是工作日调休，但交易所休市，固定排除- 同一交易日存在重复 Excel 时，会保留记录数/文件大小评分更高的一份，删除重复文件
- 发现缺失交易日且浏览器会话仍可用时，会对缺失日期再尝试下载一次
- 重试后仍缺失时，会在页面输出缺失日期提醒，但继续生成报告，便于先查看已覆盖数据
- 预期交易日按“周一至周五”和
- 本地目录生成报告前也会按同一交易日规则检查已解析日期；缺失只提醒，不阻断生成
- 该入口仅应用于你本人合规访问的账户数据，不应用于规避验证码、频控、平台访问限制或网站使用条款
- 客户权益、单位净值、期末份额
- 累计净利润、累计手续费、最大回撤、夏普比率
- 顶部固定期间收益率：上周、上月、本月、YTD。自然周/月以生成报告当天为锚点；分析历史区间时，若数据不覆盖当前自然周期，相应指标会显示“数据不足”。上周收益率优先使用上上周最后一个有效交易日到上周最后一个有效交易日的单位净值边界；月度收益率同样优先使用期间开始前边界。若缺少期初边界但目标周/月内至少有两个有效净值点，则退回为期间内首末有效点计算；仍不足两点时显示“数据不足”。YTD 使用当年第一个有效净值点到报告最后一个有效净值点计算。这些收益率基于单位净值边界计算，不是把期间日盈亏简单相加
- 每周/每月盈亏与净值曲线
- HTML/PDF 报告和下载的净值 Excel 会提示：当前净值计算仅供参考，若相关出入金对份额影响不符合实际，请自行人工再调整
- 出入金类型汇总
- 出入金分类汇总
- 出入金发生日期明细
- 页面中“出入金”类型会显示为“非银期出入金”，避免和银期转账混淆
- 发生日期明细支持按银期转账、手续费返佣、返息、其他筛选，默认全选，并可下载当前筛选明细 Excel
- 备注语义尽量保留，账号类数字自动脱敏
- 隔夜净名义暴露
- 隔夜净暴露 / 客户权益比例
- 保证金与风险度辅助信息
- 平仓贡献
- 盯市变动贡献
- 结算贡献
- 净盈利
- 手续费、峰值保证金、收益曲线与成交分布
- 收益曲线默认展示各板块区间累计净盈利，单品种默认不勾选，不显示勾选品种合计曲线
- 权利金收支
- 结算贡献
- 净盈利
- 手续费、峰值保证金、收益曲线与成交分布
- 期权品种收益支持按板块筛选和板块合计曲线，布局与期货收益曲线一致
- 收益曲线默认展示各板块区间累计净盈利，单品种默认不勾选，不显示勾选品种合计曲线
PTA看涨期权、白糖期权、铜期权、红枣期权等展示名会按标的归入对应板块
- 成交笔数、活跃交易日、成交总手数
- 平仓胜率、盈亏比、平均持仓天数、中位数、日内平仓占比
- 持仓周期分桶统计：
- 日内
- 1日
- 2-3日
- 4-7日
- 8-14日
- 15日以上
账户收益、分品种收益、毛收益、净盈利和顶部闭环验算，统一使用结算型口径。
闭环公式：
期货分品种结算净利润 + 期权分品种结算净利润 + 非份额型出入金净额 + 交割相关调整 = 账户累计净利润
交割相关调整 = 交割盈亏 - 交割手续费
累计净利润以区间首日收盘客户权益为基准。若区间首日刚好有银期入金或出金，这笔现金流已经体现在基准权益里，不会再从累计净利润中重复扣减；报告顶部的外部出入金净额指基准日之后的份额型外部出入金。
- 平仓胜率、盈亏比、持仓周期胜率、平均单笔完整持仓盈亏
- 优先使用开仓价到平仓价估算完整持仓盈亏；无法可靠估算时退回结算单平仓贡献
- 默认未扣手续费
- 不参与账户累计净利润闭环
- 缺少可靠开仓日期或开仓时间的平仓记录，不强行归入持仓周期桶
会改变份额的流水：
- 银期转账入金
- 银期转账出金
- 其它实际外部银行出入金
不会改变份额、但会影响累计净利润的流水：
- 手续费返还 / 返佣
- 利息返还
- 申报费
- 行权手续费
- 其它非份额型流水
普通交易手续费如果同时出现在成交明细和资金明细中，报告只使用成交明细里的手续费字段，避免重复扣减。
但 行权手续费 通常不在成交明细手续费中完整体现，应作为非份额型成本保留，并参与顶部闭环验算。
保证金监控中心 Excel 中的“浮动盈亏”通常是截至当日的余额，不是当日新增值。 因此期货盯市变动贡献必须按：
当日浮动盈亏 - 上一结算日浮动盈亏
换算后，才能与 txt 结算单中的“持仓盯市盈亏”口径对齐。
监控中心 Excel 中的期权合约代码不总是标准的 品种月份-C/P-执行价 形式，也可能出现郑商所白糖等写法，例如：
SR605MSC5500
SR605MSP5200
这类合约应识别为期权，并映射回对应中文品种，而不是归入期货持仓。 解析监控中心 Excel 时还会在新章节标题处停止当前表格读取，避免“期权成交汇总/期权持仓汇总”串入“期货持仓汇总”，导致分品种盯市收益被误算。
当前闭环验算主要面向常规期货 / 期权结算、常规出入金与费用流水；其中 行权手续费 已按非份额型成本纳入闭环，结算单资金状况中的 交割手续费 和 交割盈亏 会按 交割盈亏 - 交割手续费 作为交割相关调整单列。以下业务仍可能需要单独核查：
| 业务类型 | 影响 |
|---|---|
| 复杂交割归因 | 交割手续费和交割盈亏总额已纳入闭环，但交割明细按品种/合约拆分、实物交收路径和收益归属仍可能需要人工核查 |
| 行权 / 被行权的标的持仓变化 | 期权权利金、标的持仓变化与收益归因可能需要单独建模；行权手续费本身已纳入非份额型成本 |
| 实物交收 / 仓单相关处理 | 不适合直接套用当前分品种收益归因逻辑 |
| 套利合约 | 组合合约、跨期/跨品种价差合约可能需要拆分腿或特殊映射，否则分品种收益归属可能无法与账户口径完全闭环 |
| 期转现等特殊履约处理 | 可能改变持仓与资金变化路径 |
| 期货公司特殊自定义字段 | 不同公司格式差异可能导致字段无法标准化解释 |
如果数据中包含上述业务，分品种结算贡献与账户累计净利润之间可能无法完全一致。 这不一定表示程序出错，而是说明该类业务尚未纳入当前模型。
- 本项目是通用的软件工具，不是持牌期货经营机构、投资顾问、资产管理人、会计师事务所或律师事务所，也不代表上述任何主体提供服务。
- 项目作者和发布者不掌握使用者的账户状况、风险承受能力、交易目的或完整业务背景，不对任何报告作适当性判断，不保证数据、公式、分类、图表、收益率、净值、风险指标或导出文件准确、完整、及时、持续可用或适合特定目的。
- 使用者应独立核验结果、独立作出决定并独立承担交易及其它使用后果。发现缺失日期、验算差额、未知字段、异常值或未覆盖业务时，应停止依赖相关结果并回到原始资料人工核查。
- 结算单、资金流水、客户号、成交明细、浏览器 profile 和生成报告可能包含个人信息、敏感信息、商业秘密或受合同保密义务约束的数据。
- 使用者应自行确认具有合法的数据来源、访问权限和处理依据，并负责数据最小化、访问控制、保存期限、安全措施、备份、删除、跨境处理及对外分享。
- 内置脱敏是降低误泄露概率的辅助措施，不保证识别所有账号、姓名、备注、文件名、路径或可重新识别的信息。分享任何 HTML、PDF、Excel、CSV、日志或截图前必须人工复核。
- 项目默认在本机运行不代表绝对安全；操作系统账户、浏览器扩展、同步软件、恶意软件、备份服务、共享目录或错误的监听地址仍可能造成泄露。
- 保证金监控中心、期货公司、交易所、Chrome、Chromium 及其它第三方名称，仅用于说明数据来源、兼容性或运行依赖。除非另有明确书面说明，本项目与这些机构或产品不存在隶属、授权、合作、认证、赞助或背书关系；相关名称和商标权利归各自权利人所有。
- 第三方网站、页面结构、接口、验证流程、服务可用性和规则可能随时变化。本项目不保证相关自动化持续可用，也不负责第三方服务的内容、安全性或行为。
- 使用者必须遵守第三方服务当时有效的协议、访问规则和技术限制，不得利用本项目绕过验证码、登录控制、频率限制、权限边界或其它保护措施。若项目行为与第三方规则冲突，应立即停止使用相关功能。
- 本项目按 LICENSE 所述的“现状”和“可获得”基础提供；无担保及责任限制以 LICENSE 和适用法律为准。
- README、LICENSE 或界面中的风险提示不能替代具体场景的合规审查，也不保证在所有司法管辖区均产生相同法律效果。
- 若计划团队共享、处理他人或客户数据、对外发布报告、托管部署、提供收费服务、用于组织内部生产流程，或无法判断数据和平台授权边界，应在使用或发布前咨询熟悉适用地区、数据保护及证券期货监管规则的专业律师。
- 本 README 仅说明软件功能、限制和工程风险，不构成针对任何个人或组织的法律意见。
因为有些平仓记录虽然可以判断盈亏，但缺少可靠的开仓日期或开仓时间，无法安全归入某个持仓周期桶。
这是当前前端下载流程和监控中心使用场景下的约束，避免超出可稳定批量处理的日期范围。
页面默认分页展示；导出 PDF 时会展开当前筛选窗口内的全部明细。
PDF 导出会使用打印模式优化图表分页：期货/期权品种收益曲线默认切到净盈利、清空单品种、勾选各板块合计曲线并以当前区间起点归零；大型饼图、横向柱状图等图表会压缩到单页高度并避免在页中间断开。普通短表格、口径说明框和指标卡会尽量整块保留在同一页；净值近 30 日、分品种统计等长表格允许自然分页，并在分页后重复表头。出入金发生明细在 PDF 中只展示筛选范围内最近发生日期的第一页，完整明细以 HTML 报告为准。
期货/期权品种收益曲线支持各自独立选择开始日期和结束日期，不会跟随账户净值曲线的时间窗口联动。曲线仍先按全历史结算型累计收益计算，再裁剪当前展示窗口；“当前显示区间起点归零”只影响当前窗口的展示基准，不改变底层累计收益口径。导出 PDF 时会保留 HTML 页面当前选择的品种曲线时间段。
常见原因包括：
- 当前日期窗口把该交易日过滤掉了
- 同一交易日存在重复来源，被自动去重
- 该文件实际不是可解析的有效结算单
生成前校验只负责提醒数据覆盖是否完整，不再阻断计算。若验算差额集中出现在缺失日期之后，应优先补齐对应结算单；小额残差也可能来自结算单账户摘要与持仓汇总字段不一致，或复杂交割归因、行权/被行权、套利合约等特殊业务尚未完全建模。 本地目录和保证金监控中心入口都会在生成完成结果里用红色加粗显示缺失交易日提醒，便于第一时间发现数据覆盖不足。
- 项目后端不接收或保存保证金监控中心账号密码；凭据只应由用户在第三方官方登录页面中输入。浏览器与第三方网站之间的网络通信仍受该网站、浏览器和本机环境控制
- 对外分享 HTML / PDF 前，请先检查是否还需要进一步脱敏
- 原始结算单、下载目录、生成报告目录不要提交到 Git
- 客户号位数不做固定假设，独立账号类数字会按规则脱敏
- 安全边界、漏洞报告方式和发布前检查见 SECURITY.md
- 可以在理解 GitHub Public 仓库查看、fork 和缓存边界的前提下公开托管源码，但必须保留
LICENSE、风险提示，并确保提交历史从未包含真实结算单、报告、账号、浏览器 profile 或凭据。 - 不建议公开 PyPI、公开 SaaS、公开 Web 演示站或面向不特定对象提供批量分析服务。
- 不要在 Issue 或 Pull Request 中接受真实业务数据作为复现样例。外部贡献者应保证其提交内容有合法来源，并同意其贡献适用本仓库 LICENSE；涉及第三方代码、数据格式样例或不明确权利来源的贡献不应合并。
在源码目录执行：
PYTHONPATH=src python -m unittest discover -s tests -v