pfor-qmt 0.1.0__tar.gz

pfor_qmt-0.1.0/AGENTS.md

@@ -0,0 +1,98 @@
+# Repository Guidelines
+
+## 计划模式约束
+总是把在计划模式下创建的计划保存到 <project_folder>/docs/plans/ 目录下，计划文件名为 <feat-plan-YYYYMMDD>.md ,计划模式下的所有操作都必须在计划中记录，不能直接修改数据库或配置文件。
+
+## 协作与执行原则
+
+使用简体中文沟通。先阅读相关实现，再修改；优先复用已有代码和测试，以最小必要改动完成已确认需求。重大假设必须说明，普通实现细节自行解决。
+
+用户已授权实施确认过的计划，不重复请求同类授权。缺少数据库连接或终端配置时，继续完成不依赖这些信息的开发；不得编造连接信息或宣称实机验证通过。
+
+保留用户已有改动。不得修改源项目 cfquant 的工作区，不得替换其他应用的配置、数据库或 QMT 模型。每次交付说明实际变更、验证结果和未完成事项。
+
+## 项目定位与范围
+
+pfor-qmt 是基于 cfquant 派生的行情、指数查询和历史数据库工具。
+
+支持一个大 QMT 行情源。2026-09-17 用户确认扩展为股票、行业概念、指数、期货、期权、场内基金、债券七类，优先完成期货和期权；覆盖终端实际提供的国内品种。提供实时行情、日线、1/5 分钟线、当前成员、PostgreSQL 存储及 CSV/Parquet 导出。
+
+保留 QMT 合约代码大小写和交易所后缀，区分普通合约、连续合约及组合合约。期权标的、行权价、到期日等仅使用终端资料，不从名称猜测。行业概念属于板块与成员关系，不伪装为可交易证券或有独立K线的指数。期货夜盘时间与交易日分别保存，无法确认交易日归属时标记待核验，不套用股票交易时段。
+
+2026-09-17 用户确认增加 Tushare 期货数据源与多账号管理：目录、期货日历、主力映射、日线及具体月份合约的 1/5 分钟历史。复用统一目录、任务、K线表、查询和导出，不自动切源、混源或轮换 Token。主力连续分钟拼接、Tushare 实时行情及研究接口不在本次范围。
+
+2026-09-18 用户授权扩展 Tushare 周/月线、15/30/60分钟、独立交易日历与主力映射同步、仓单及每日成交持仓排名。均复用现有任务、账号和schema；非K线资料按自身维度建表。2000积分不等于分钟授权；Tick无API，不构造下载入口或模拟数据。连续分钟仍通过映射选择实际月份合约，不合成连续序列。
+
+第一期不提供交易、资金持仓查询、自动多源路由、LTtx 高级模式、LITE 模式、Level2、千档、财务研究、公式、历史指数成分与权重、自动登录或在线更新。新需求不得因上游已有代码而自动纳入。
+
+## 源码来源与许可证
+
+固定上游提交为 5baa4daf8dab01fb415afdd45a72cd254cea042f。从该提交提取经过筛选的受版本控制文件，不复制本地工作区、忽略文件、运行数据和凭据。
+
+保留 MIT 许可证、Copyright (c) 2026 tao 及适用版权声明。记录实际使用的第三方代码、资源及许可证。产品文案注明派生关系，不冒充上游官方产品。
+
+UPSTREAM.md 记录来源、路径映射和修改理由；COMPATIBILITY.md 记录保留、修改、移除、新增接口及验证状态。后续上游同步采用选择性移植和回归测试。
+
+## 目录与工程边界
+
+pfor_qmt/ 存放 SDK、服务及业务模块；qmt_scripts/ 存放终端入口；web_dashboard/ 存放静态界面；tests/、tools/、docs/ 分别存放测试、工具和文档。
+
+runtime/、log/、导出文件及本地连接配置不提交。AGENTS.md、迁移脚本、来源说明、兼容矩阵和依赖锁定文件必须提交。
+
+统一使用根目录 config.toml 管理本地配置，提交无凭据的 config.example.toml。优先级为显式命令行参数、环境变量、TOML、默认值；网页设置写回同一文件。QMT 内嵌端只接收部署器生成的行情参数，不复制数据库凭据或 API Key。
+
+主程序使用 Python 3.12；QMT 内嵌代码保持 Python 3.6 兼容和必要的 GBK 编码。普通源码使用 UTF-8。Python 使用四空格缩进，前端沿用两空格和现有风格。
+
+复用上游成熟实现，不为未来需求预建复杂抽象。迁移、命名调整、缺陷修复和新增功能分阶段提交，避免混入整库格式化。
+
+## 行情桥与命名隔离
+
+使用 pfor_qmt 包、pfor-qmt 命令、独立管道和模型、独立运行目录及数据库 schema。
+
+命名变更逐项检查导入、配置、资源、模型识别及清理逻辑，不做全局字符串替换。保留的协议标记须有记录。
+
+SDK、HTTP 和桥端仅开放明确允许的行情操作，包括订阅和历史下载。不得初始化交易回调或暴露交易 action；不能仅通过隐藏网页入口裁剪交易功能。
+
+部署器只能管理 pfor-qmt 自有模型和文件，不得清理、停用或覆盖既有 cfquant 模型。
+
+## 数据与任务约定
+
+2026-09-20 用户授权QMT交易日历与主力映射接入。当前主力必须来自终端明确返回，采集快照与历史逐日映射分别保存，缺交易日保留NULL。完整日历、观察到的K线日期及未知日期须区分，旧QMT日历不自动升级。能力检测不因函数存在或空响应宣称可用、无权限；不得新建MiniQMT连接或借用Tushare数据填补。
+
+2026-09-20 历史行情汇总必须使用可分页表格，不用无边界指标块堆叠；主力映射和结算参数展示名称时只使用同源证券目录，代码作为辅助标识，缺名称不得猜测。图表、列表和详情保留原始精度与NULL。
+
+2026-09-20 用户授权在适合的列表增加删除能力。配置、任务和导出记录采用可恢复回收站；配置恢复后保持停用，活动任务及配置依赖须校验，旧任务证据与行情文件保留。默认工作列表排除回收站，质量核验不得因此丢失未解决问题。测试删除流程仅使用隔离schema，不删除用户业务记录作为验收。
+
+2026-09-18 用户授权新增Tushare结算参数fut_settle与主要品种交易周报fut_weekly_detail，复用现有资料、任务、维护、核验和导出链路。结算费率和手续费保留上游原值，不猜测百分比基准；周报金额亿元精确换算为元并保留原值，保留原始week（含旧非补零格式）与week_date，不假定为ISO周。周报不能按逐日行情规则判缺口。
+
+PostgreSQL 保存不复权行情及可获得的复权因子。明确区分 QMT 数据与数据库数据，保留字段单位、数值精度、时间语义和来源。
+
+按稳定合约 ID、数据来源、周期和行情时间去重并更新；账号不是数据来源维度。原始代码通过来源映射保留，资料不足不猜测跨源合并。交易时间按 Asia/Shanghai 解释。空值不补零，缺行情不伪造，当前成分快照不冒充历史成分。
+
+Tushare 凭据只保存在本地统一配置或环境变量中，API 不回传 Token。任务固定账号与端点，不受默认账号变化影响。日线成交额万元转换为元，分钟成交额保留元，Decimal/NUMERIC 保留精度；旧 QMT 单位未核验前不改写。无明确交易日的分钟保留空值和待核验状态。
+
+周/月线周期标签和计算截至日期分别保存，未结束周期以not_published标记等待周期结束，不用日线逐日覆盖规则校验。仓单保留单位和仓库/等级/年度等明细维度；持仓排名的未上榜字段保留NULL，不计算虚假的名次。闭市日不能参与自动交易日调度；INE持仓数据按官方SHFE入口读取并保留返回交易所。
+
+下载完成必须以实际读取、校验和入库结果为依据。请求返回、拿到订阅号或读到空表均不等于业务成功。旧接口回退必须覆盖全部请求证券。
+
+任务持久化检查点，支持重启恢复、取消和失败重试。同一行情源只执行一个补数任务；取消只停止后续处理，不能声称撤销已经发送的终端请求。
+
+迁移和业务写入限定在 pfor_qmt schema。凭据不进入代码、日志或导出文件；自动化测试使用隔离测试 schema，不使用用户业务数据。
+
+## 验证与交付
+
+2026-09-18 全链路整改约定：执行状态与数据质量分别记录；partial 显示为部分完成，不再统称待核验。同一合约分块的坏数据不得入库，独立合约继续；认证、连接和数据库故障不得被误报为普通缺口。重试创建关联任务，只处理未完成范围，不覆盖原任务证据。
+
+自动维护覆盖已接入资料，但仅作用于用户明确保存的维护范围；不扩大证券选择，不自动切源或轮换账号。权限错误不自动重试，网络请求最多重试三次，业务补数必须有次数和时间边界。站内健康与日志面板报告可行动异常；任务事件保留90天，脱敏异常样本保留30天，不清除行情数据或未解决问题的定位信息。
+
+筛选与采集支持多选、全选、跨页保留及取消还原；全选匹配结果须按同一数据库快照读取，超限明确报错，不静默截断。批量写入先完整校验，再原子创建原有类型任务，保持账号绑定和取消恢复语义；来源与采集账号保持单选，不跨来源拼接结果。
+
+快捷日期按 Asia/Shanghai 计算并包含结束日；月、年按日历回退并处理月末。记录详情保留单位、来源、NULL与原始字段；多证券多周期表格必须有明确标识，图表只展示一个证券和周期。浏览器测试覆盖筛选重置、跨页全选、批量确认取消及窄视口详情。
+
+迁移接口使用相同模拟 QMT 输入与上游对比，验证参数、结果、字段、回调及错误行为；所有预期差异写入兼容矩阵。
+
+覆盖交易请求拒绝、命名与部署隔离、订阅退订、下载回退、重复入库、断线恢复、任务取消、调度去重和文件导出一致性。
+
+Web 修改执行浏览器流程与桌面、移动视口检查。构建产物必须包含许可和必需资源，不得包含本地配置及运行数据。
+
+分别报告离线通过、实机通过、失败和未验证；不得跳过或弱化失败测试以满足验收。

pfor_qmt-0.1.0/COMPATIBILITY.md

@@ -0,0 +1,184 @@
+# 兼容矩阵
+
+## QMT春节空区间判定（2026-09-22，schema12不变）
+
+原SOURCE_NOT_READY将目标区间的行情和合约K线日期同时为空误导为连接问题；现在明确空结果原因尚未确认，需分别检查休市、合约范围、缓存和连接。原错误码和停止检查点行为对未知区间保持。
+
+对郑商函〔2025〕939号明确的2026年郑商所七段节假日休市区间，只有QMT日线/1分钟/5分钟的整个请求区间落入同一休市段，实际读回为空、同源日历无开市冲突且库内无该对象行情时，记录EXCHANGE_HOLIDAY_CLOSED/not_applicable并推进检查点。该规则同时用于离线核验，保存公告名称、出处、日期和规则版本；不把公告内容写作QMT返回的交易日历，不覆盖行情或已保存的开市证据。
+
+含节前/节后交易日、普通周末分钟、其他交易所、其他年份及Tushare均不套用此规则。数据源请求异常仍按实际错误处理。公告依据：建信期货转载《郑商所关于2026年部分节假日休市安排的通知》（2025-12-17），https://www.ccbfutures.com/main/a/20251217/76267.shtml 。
+
+## 数据库注释与连接诊断（2026-09-21，schema12）
+
+012_schema_comments.sql仅执行COMMENT ON TABLE/VIEW/COLUMN，为22张表、1个视图及229个字段补充中文业务口径；不改变列、约束、索引或业务行。tools/generate_schema_docs.py从系统目录生成docs/DATABASE_SCHEMA.md，真实外键与JSON/代码逻辑关系分图说明；--check可校验文档漂移。
+
+Store.connect仅在连接建立及会话初始化阶段有限重试暂时连接故障，最多3次；认证和业务SQL失败不重放，事务提交期间失联也不自动重放业务。DATABASE_ERROR代码保持兼容，错误说明按SQLSTATE区分空间、内存、连接数、缺表/字段、权限、只读、约束、超时等原因；不输出数据库驱动原始消息或凭据。旧失败任务证据保持不变。
+
+## QMT原生返回适配修复（2026-09-21，schema11不变）
+
+get_main_contract实际可能返回无市场后缀的月份代码；仅对合法月份返回值补上请求合约的同市场后缀，不修改通用证券代码校验。保留原始返回，近月连续别名须用终端双方ProductID核对并保存证据；离线核验使用该证据，不请求终端。
+
+共享合约分类中，L连续标记只接受1至2位编号，PL611.ZF、TL2612.IF等正常月份合约不再误判；cuL0.SF、IFL00.IF等既有连续类型保留。原目录中已实机核对的PL611.ZF、TL2612.IF同步修正分类。
+
+旧桥动作未开放与终端原生接口缺失分别报告QMT_BRIDGE_OUTDATED和QMT_TERMINAL_UNSUPPORTED。只有前者建议更新PFOR_MARKET。当前大QMT没有独立日历时，使用同源目录中每市场最多三个连续合约的日K线日期并集，存为bar_observation，仅证明这些日期曾观察到交易，其他日期未知。权限/连接错误不触发回退；不借用其他市场或来源，不推断休市、节假日或未来开市，不覆盖权威日历的相反证据。
+
+日历能力显示limited（有限可用），任务保留partial及CALENDAR_OBSERVATIONS_ONLY；历史映射空缓存仍显示empty，不声称权限不足或已取得历史关系。本轮只更新主程序，无数据库迁移或终端模型变更。
+
+## QMT日历和主力映射接入（schema11）
+
+保持旧Tushare资料调用默认；新增QMT来源及mapping_mode=current|history，当前模式忽略业务日期筛选，只读最新保存快照。schema11为日历增加证据/时间/原始字段、历史映射增加原始字段，并新增共享快照表与最新快照视图。旧日历默认legacy，不改写行情，不升级旧证据为完整日历。
+
+当前快照不作为历史映射，日历缺证据保持未知；离线核验原任务时仍读取原任务快照。当前快照及日历维护使用自然日，历史映射维护需要完整同源日历。只读能力检测不发下载，空缓存不等于无权限。新桥仅增加定向行情动作，旧桥以明确升级提示处理，不自动换连接或扩展普通行情周期白名单；本轮部署和实机结果以验证记录为准。
+
+## QMT 周末日线空结果（2026-09-20，schema10不变）
+
+QMT 国内日线请求范围仅含周六/周日、实际回读为空、日历为空且同源已保存日历无开市证据时，分块改为 `not_applicable / DAILY_WEEKEND_CLOSED`，允许推进检查点；0行任务明确显示“全部分块不适用，未写入记录”。该结论不代表连接通过，不生成行情或交易日历。只读核验使用相同规则，已有行情或开市证据不被覆盖。
+
+工作日、跨工作日范围及分钟空结果仍保留原就绪检查；Tushare不使用该规则。QMT周期白名单仍为 `1d/1m/5m`，没有增加聚合周期或修改终端桥。历史任务证据保持不变，重试通过关联新任务记录结果。
+
+## 历史汇总与资料名称展示（schema10不变）
+
+历史网页汇总从指标块改为客户端分页表，查询接口仍返回完整groups；新增instrument_names只读字段。期货summary/page对mapping/settle附带同源证券名称映射，代码和值字段不变，缺名称明确显示未收录，不跨QMT/Tushare借名。
+
+## 期货资料明细筛选（schema10不变）
+
+资料查询、统计与导出新增可选dimensions，省略时保持原范围；仓单支持warehouse/unit，排名支持broker。新只读filter-options接口从同一数据库范围获取完整可选值，数量超限明确拒绝。CSV/Parquet及元数据保持精度、NULL与筛选范围。采集和维护拒绝查询专用dimensions；网页采集确认后仅传原有交易所、对象与日期范围。不迁移数据库或改变上游接口参数。
+
+## 查询上下文与任务定位（schema10不变）
+
+units接口增加可选筛选、total和limit，不改变分块内容或旧无筛选调用；事件查询增加search及任务ID前缀支持，任务详情事件接口仍固定完整ID。SDK对应方法接受可选筛选。前端修正未应用条件与展示设置混用、异步选项恢复覆盖新编辑及任务详情返回路径，不改写数据或任务状态。
+
+## 回收站与列表补齐（schema10）
+
+datasets、maintenance_plans、jobs增加deleted_at，默认NULL，不改写原数值。回收配置自动停用，恢复不自动启用；任务回收保留状态及追溯数据，默认列表与执行统计排除回收站项，质量证据继续纳入核验。迁移增加活动任务/自动更新约束及配置引用入队保护。原未回收记录的接口结果保持，新增trash筛选和delete/restore接口；不提供行情或文件物理清理。
+
+## 列表筛选与分钟成员选择（2026-09-20）
+
+任务列表增加只读origin、dataset_name、maintenance_name字段；名称来自当前关联配置，不改写原任务payload。jobs/query与operations/summary共用名称/成员代码搜索及account_ids、origins可选筛选，省略时保持原范围。Tushare分钟成员约束不放宽，前端全选按具体月份合约过滤，后端错误补充不兼容代码。旧接口、采集权限、任务状态及schema9保持。
+
+## 全局来源与运维导航修复（2026-09-20）
+
+Web来源改为工作台全局选择，保存在浏览器中；移除进入特定页面时的隐式切源。不支持的能力明确提示，既有任务绑定不变。Web列表强制使用当前来源；GET /datasets、/maintenance、/runtime/events、/health新增可选source，不传时维持原跨源结果。health可选view=overview或quality按需读取，默认保留完整返回字段。健康统计将任务来源先物化，再与分块关联，避免大payload反复解压；不改变质量判定和原数据，不迁移schema。
+
+## 维护执行闭环补齐（2026-09-20，仍为schema9）
+
+修复console维护从旧任务派生时重新解析数据集的问题，改为固定原任务范围与账号端点；裸dataset_id仍明确表示采用当前数据集。暂停配置允许保留不可用绑定，启用、预览、确认执行均校验端点及权限。数据集仅在账号改变或rebind_account=true时重新绑定端点。执行一次开放自定义日期，解决首次交易日历维护没有日历可用的前置循环。图表query_scope同时校验证券、来源、周期和日期范围。未新增数据表或改写既有行情、任务。
+
+## 独立工作台与分析接口（schema9）
+
+新增history/summary、history/chart、futures/summary、operations/summary、datasets/query、maintenance/query及SDK方法；旧历史接口省略新增排序/总数/快照参数时保留原行为。目录/板块/任务/资料支持白名单排序；资料与任务增加快照元数据，现有rows和单位保留。
+
+新console管理接口要求配置revision；config_revision防止设置表单覆盖其他窗口。旧SDK维护接口保持兼容，新工作台创建维护默认停用。scope-preview比较语义而非JSON键顺序，执行预览有效期五分钟，同一预览只创建一次任务；不推进自动维护游标。既有任务payload不随数据集编辑改变。
+
+schema9仅为datasets、maintenance_plans增加revision和配置变更触发器，并增加任务查询索引。自动维护游标和故障状态变化不增加配置版本。QMT协议、终端模型、行情数值和导出格式均未修改。Web旧hash有兼容跳转，单页多资料切换改为各资料独立地址；后台多资源批量接口保留。
+
+## 结算参数与交易周报（schema8）
+
+新增fut_settle与fut_weekly_detail适配，资料resource分别为settle、weekly_detail；原holding接口、SHFE/INE口径及字段保持。沿用任务/账号/事件/核验/查询/导出，无新任务类型。新迁移仅增加两张资料表。结算量率原值保存；周报amount/cumamt精确换算亿元到元并增加原始金额字段及转换版本。按week_date查询、保留原week格式，不推算ISO周，不逐日判断周报缺口。旧资料返回形状不变，来源仍固定tushare。
+
+## 核验到补数
+
+schema仍为7，不另建补数表。新增repair-preview、repair、links接口及SDK方法；补数复用download，payload.repair_of关联核验、repair_units保留选择、repair_preview_key校验确认范围。原retry仍保持原任务类型，不将只读核验重试偷偷转为采集。关联列表分页，原任务状态与证据不改写。补数不继承dataset_id或maintenance_id，避免新增自动范围；重新核验只保留verification_of，去除补数关联的旧字段。
+
+## 自动维护闭环
+
+不增加schema版本，继续使用schema7。POST /maintenance/{id}新增可选名称、时间、回读天数，原enabled开关仍兼容；SDK新增update_maintenance。重复启用不重置起始日，数据集与关联维护计划禁止双重启用。新调度按范围/交易所/结束日生成键，旧日期键根据原任务实际范围继承，不重写旧任务。全局事件根据context.source保留Tushare来源，权限阻塞与恢复可追踪；界面使用同一编辑表单，暂停状态不因编辑而改变。
+
+## 数据核验（schema7）
+
+jobs新增verify类型，复用现有coverage/job_units/job_events。POST /jobs/{id}/verify与DataClient.verify创建独立只读核验；不改行情、不重写原任务、不改变采集账号绑定。GET /runtime/events不依赖数据库。新鲜度的周/月及目录状态使用实际日历与分块证据，允许not_published/rejected。自动补数基于整个原任务链计算剩余范围和总尝试次数；采集与核验使用coverage-v2规则。详细依据与未验证项见docs/QUALITY_VERIFICATION.md。
+
+## 新鲜度与恢复验证（2026-09-18）
+
+新增POST /freshness/query和DataClient.freshness；GET /health增加scheduled_freshness分页对象。仅评估启用的数据集与维护计划，返回逐对象目标日期、实际日期、状态、原因及动作，不覆盖原任务状态或质量。无schema迁移、无数据源请求，旧历史与导出接口不变；分钟及未核验发布规则不冒充已验证。备份恢复工具仅创建无网络临时容器，校验后清理，不向业务数据库恢复。
+
+## 执行与数据质量（2026-09-18）
+
+schema6保留原行情、目录、资料与任务记录，新增job_units、job_events和maintenance_plans。迁移将旧成功状态completed转换为succeeded；/jobs/query仍接受completed筛选，但响应统一为succeeded。新增retrying、blocked；partial显示部分完成，不再表示统一的待核验。
+
+POST /jobs/{id}/retry改为返回新的关联任务，parent_id指向原任务，原状态不改写。可传unit_indices只重试指定分块；已成功范围和仅缺交易时段规则的分钟范围不重复采集。相同活动重试去重，不同范围明确拒绝；客户端需使用响应中的新id。旧覆盖记录保留，旧任务不会被伪造为已通过新校验。
+
+新增GET /jobs/{id}/units、/jobs/{id}/events，POST /events/query，GET /health及GET/POST /maintenance、POST /maintenance/{id}。SDK对应job_units、job_events、query_events、health、maintenance_plans、create_maintenance、set_maintenance。现有任务表和队列复用，来源/账号/端点不变，不升级QMT模型。
+
+数据质量以分块记录，不把任务完成、校验通过与全市场连续性等同。仓单/排名空日因缺少发布证据保持待核验；分钟时段与夜盘归属未确认时保持待核验。维护范围需要从原始采集任务显式保存，默认五交易日回读；权限问题不做网络或业务自动重试。
+
+## 批量筛选与任务（2026-09-18）
+
+不新增迁移，保持schema5。目录GET筛选兼容单值并接受逗号多值，新增POST /catalog/select保证同一快照全选，超过10000项明确失败。Tushare目录同步新增可选exchanges，不传仍为六所。
+
+新增/history/query、/downloads/batch、/exports/batch、/jobs/query和相应DataClient方法；旧单对象接口形状保留。批量回补按各数据集周期交集，单任务/downloads仍要求严格子集；来源必须一致，各自固定账号与端点。批量请求先全部校验再原子创建任务，不修改既有任务。
+
+资料records/sync/export新增selections：同类型查询、多类型分任务同步和导出。旧单目标仍返回单任务，新selections形式返回jobs数组。每个分块持久化目标，旧检查点仍可恢复；不增加并行源请求、轮换账号或第二套数据表。历史批量结果逐行保留来源、周期、转换版本；图表不混合多个序列。
+
+Web新增搜索多选、跨页全选、快捷日期、结构化详情及任务筛选分页。数据来源、采集账号、单指数映射与诊断仍按原单选语义。分钟无权限仍禁用采集，不影响已有历史导出。回归及真实数据验证见docs/VERIFICATION.md。
+
+## 期货资料与周期扩展（2026-09-18）
+
+schema5扩展现有bars和trading_dates，并在同一pfor_qmt schema增加仓单、会员持仓明细表；没有第二套行情库、账号或任务系统。迁移前后137,687条既有行情的原字段哈希一致，原下载任务及检查点未改写。完整回归239项通过，真实小样本和文件一致性见docs/VERIFICATION.md。
+
+| 接口或能力 | 处理 | 验证状态与差异 |
+| --- | --- | --- |
+| /futures/options、sync、records、export；DataClient同名资料方法 | 新增 | 独立日历、映射、仓单和成交持仓排名；同步复用download队列，导出复用export队列，账号及端点固定 |
+| fut_trade_cal | 扩展 | 保存开市、休市及前交易日；六所各7天实测通过；旧/calendar仍仅返回开市日，闭市日不参与调度 |
+| fut_weekly_monthly | 新增 | 1w/1mo，仅Tushare；金额万元转元，time为周五/月末标签，as_of_date为上游计算截至日，不是历史时点快照；8周、2月实测通过 |
+| ft_mins | 扩展 | 1/5/15/30/60分钟；模拟频率及8000行截断边界通过，真实账号仍权限拒绝；不拼接连续分钟 |
+| fut_wsr | 新增 | 保留产品名称、仓库、年度、等级等维度及原始单位；SHFE/CU的铜与铜(BC)分别保存，DCE/A与SHFE/CU实测21及42条 |
+| fut_holding | 新增 | 保留会员和可空数值，不伪造名次；DCE/A2611实测29条，INE按SHFE入口返回空，不能视为该市场已验收 |
+| fut_mapping | 扩展 | 单独同步、查询、导出及月份合约跳转；A.DCE实测4条，重复同日冲突明确失败 |
+| CSV / Parquet | 扩展 | 资料按自身字段和单位导出；仅周/月行情额外增加as_of_date、source_fields，旧日/分钟字段形状保持；真实全字段比对通过 |
+| Tick | 未接入 | 官方无API、独立CSV交付；只展示能力状态，不构造不存在的接口或未经样本确认的导入格式 |
+
+资料当前手动同步，K线数据集沿用可配置19:00调度。QMT仍仅1d/1m/5m，xtdata接口及终端模型不变；所有旧默认source=qmt语义保持。
+
+## Tushare 扩展（已实现）
+
+旧API省略source仍选择qmt，xtdata保持QMT语义。新增tushare来源共用目录、任务、历史库及导出；多账号仅用于认证，不增加行情副本维度。历史API保留source=postgresql表示存储层，行source和新增provider表示提供方。旧QMT数据、配置与终端模型不自动改写。
+
+schema版本4将K线唯一键扩展为合约ID/来源/周期/时间；Tushare期货金额统一为元，成交与持仓量为手，旧QMT原始单位明确标记。分钟交易日未知仍为空。2026-09-18完整回归208项通过；实机六市场目录11,275条、豆一2611日线34条及CSV/Parquet一致性通过，分钟接口返回权限拒绝。结果见docs/VERIFICATION.md。
+
+兼容大商所含下划线的月均价主力/连续代码。`/downloads`和SDK下载新增可选周期子集，省略时仍使用数据集全部周期；不改变数据集、定时调度或原失败任务。下载失败保留并展示已入库行数，未授权分钟不会被跳过后标为成功；原检查点可在授权后续跑。
+
+基准为 cfquant `5baa4daf8dab01fb415afdd45a72cd254cea042f`。这是明确裁剪后的行情产品，不宣称整个 cfquant API 兼容。
+
+| 接口或能力 | 处理 | 验证状态与差异 |
+| --- | --- | --- |
+| 协议序列化、DataFrame、缺失值 | 保留 | 固定上游协议相同输入对比、迁移测试通过 |
+| Windows 管道 RPC | 保留并隔离名称 | 本机真实管道收发、客户端重连、错误返回测试通过；hub改为按请求超时清理，避免60秒默认值提前结束180秒下载 |
+| get_full_tick | 保留 | 参数及派发检查；实机三证券盘中快照可读，订阅推送单独验证 |
+| get_market_data_ex | 保留行情子集 | 1d/1m/5m，不复权；默认 fill_data=False，与上游默认存在差异 |
+| get_local_data | 修改 | 本地读取优先第九参数 subscribe=False；不补行情，不接受复权别名绕过 |
+| get_instrument_detail | 裁剪回退 | 保留原生新旧名称；无可用能力时明确失败，不构造猜测资料 |
+| get_sector_list / get_stock_list_in_sector | 保留当前数据 | 板块树遍历与当前成分；历史 timetag 被拒绝 |
+| get_trading_dates / get_divid_factors | 保留 | 保存原始因子及观察时间；真实终端能力待验证 |
+| download_history_data / data2 | 修改回退 | 旧接口逐证券；返回只代表请求结束，不代表入库成功；回调仅在同步 RPC 有效期内接收 |
+| subscribe_quote / whole_quote | 改写纯行情实现 | 原生参数、首包、退订失败保留、客户端归属测试通过；实机Tick与指定三证券推送及退订通过短观察窗口；订阅 ID 为不透明字符串 |
+| 订阅恢复 | 修改 | 网页重连后重建订阅；直接 SDK 使用者需自行重订阅，不在回调线程同步 RPC |
+| 交易、账户、资金持仓 | 移除 | SDK 无接口；hub/桥端/HTTP 请求拒绝测试通过 |
+| 多源、高级/LITE、Level2、千档、财务、公式、历史权重 | 移除 | 不迁移对应入口或初始化逻辑 |
+| DataClient、/api/v1、数据库与任务 | 新增 | PostgreSQL 隔离测试；HTTP/SDK/文件一致性测试 |
+| /source/diagnostics | 新增 | 认证只读检查；桥、快照、本地日线与日历分离，缓存读取不等于下载验收 |
+| /catalog/* / DataClient.catalog / sync_catalog | 新增 | 完整目录后台同步、真实名称、分页、类别筛选、断点恢复；原/securities列表接口保留原有1000条上限 |
+| jobs.kind=catalog / schema版本2 | 新增 | 独立目录队列；同步按批次事务保存资料与检查点；旧下载/导出任务不改写 |
+| 七类目录 / schema版本3 | 扩展 | future/option/stock/index/fund/bond；行业概念独立快照。原etf迁为fund+subtype=etf，旧etf筛选和同步参数保留兼容 |
+| get_instrument_details / get_sector_tree | 新增 | 最多100合约批量原生资料、保留板块祖先路径；新版桥catalog_version=2；旧桥仅普通证券资料可逐一回退 |
+| get_option_detail_data | 新增行情能力 | 仅派发原生详情；不可用时明确失败，不猜测字段；不涉及任何期权交易接口 |
+| /boards/* / /catalog/detail | 新增 | 板块分页、成员快照、数据集固定成员与显式刷新；合约详情可离线查询 |
+| 衍生品代码、夜盘、结算与持仓量 | 扩展 | 保留大小写、组合空格和SHO/SZO/IF/SF/DF/ZF/INE/GF后缀；新增字段为可空，CSV/Parquet和历史API增加列；未知交易日保留待核验 |
+| 多市场日历调度 | 修改 | 不再固定上证日历，按数据集各市场成员读取；任一市场日历未就绪时不创建不完整任务 |
+| /source/diagnostics terminal_history | 新增 | 仅提取终端当日历史日志的允许字段；过去错误不推断当前登录状态 |
+| 空数据与调度失败 | 修改 | 历史和日历双空时失败且检查点不推进；只行情为空仍partial；日历异常或不足五日显式提示 |
+| WebSocket | 新增 | 独立本机8767，一次性30秒票据，任务与行情推送 |
+| WebSocket unwatch / watch确认 | 新增 | 可停止行情但保留任务推送；切换及重连丢弃旧回调；退订失败保留原订阅，非法命令不再断开连接 |
+| CSV / Parquet | 新增 | CSV BOM；空值保留；Parquet 数值使用十进制文本 string，避免任意 NUMERIC 精度损失 |
+| 独立导出队列 / status.export_worker | 新增 | 导出不等待QMT下载/调度，独立锁和类型恢复；跨类型完成顺序不再保证全局先进先出 |
+| QMT 模型部署 | 重写隔离边界 | 合成终端验证隔离、冲突及并发拒绝；进程输出UTF-8且精确匹配中文路径；实机自有桥在运行，完整重装流程待验收 |
+
+目录分类使用QMT明确的资产板块及交易所合约编码规则；不从证券名称猜测类别。SDK、hub和桥均保留相同的国内代码边界与行情动作白名单。终端权限、数据覆盖、字段单位、交易时间戳与新增品种仍需实机小样本验收。
+
+2026-09-16实机历史请求返回空表，终端日志为 `200001 / connection is not login`；日线、交易日历、分钟覆盖和实时推送均未据此标记通过。三证券重复回补及DB/SDK/文件一致性已在隔离测试验证，真实执行步骤见docs/LIVE_ACCEPTANCE.md。
+
+2026-09-17新增实机Tick/指定三证券全推行情与网页持续更新通过；短区间日线下载仍失败，当前历史请求未给出明确错误码，连接或权限待终端侧核实。未修改桥端API以猜测或绕过此故障。
+
+同日七类扩展：新版行情桥已连接，79,208条证券/合约资料与QMT及API分页核对一致；沪铜、金融期权、商品期权样本收到快照及订阅回调。ETF期权样本仅资料可读，报价为空；历史日线及日历仍为空。完整自动化168项通过，详细部署文件差异及实机范围见docs/VERIFICATION.md和docs/LIVE_ACCEPTANCE.md。
+
+分钟任务记录未确认的分钟内覆盖情况，因此可呈现「待核验」；空表永远不标记业务成功。历史库存原始数据，图表使用 JS 数值显示，表格、API 与导出保留精确十进制文本。

pfor_qmt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pbeenigg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pfor_qmt-0.1.0/MANIFEST.in

@@ -0,0 +1,17 @@
+include AGENTS.md UPSTREAM.md COMPATIBILITY.md requirements.lock THIRD_PARTY_NOTICES.md
+include config.example.toml pfor.ps1
+recursive-include docs *.md *.json
+recursive-include tools *.py
+recursive-include tests *.py
+recursive-include web_dashboard *.html *.css *.js *.txt
+recursive-include pfor_qmt/migrations *.sql
+recursive-include pfor_qmt/docs *.md
+recursive-include qmt_scripts *.py
+prune runtime
+prune log
+prune exports
+prune output
+prune .venv
+prune %SystemDrive%
+global-exclude *.pyc *.local.json
+global-exclude config.toml *.local.toml

pfor_qmt-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: pfor-qmt
+Version: 0.1.0
+Summary: Local QMT market data workspace and PostgreSQL history store
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Requires-Dist: pandas<3,>=2.2
+Requires-Dist: psycopg[binary]<4,>=3.2
+Requires-Dist: pyarrow<24,>=19
+Requires-Dist: pycryptodome<4,>=3.20
+Requires-Dist: tzdata>=2025
+Requires-Dist: websockets<17,>=15
+Requires-Dist: tomlkit<1,>=0.13
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: build<2,>=1; extra == "dev"
+Requires-Dist: playwright<2,>=1.50; extra == "dev"
+Dynamic: license-file
+
+# pfor-qmt
+
+数据库结构、ER图、字段口径和主外键说明见[数据库字典](docs/DATABASE_SCHEMA.md)。表及字段注释由版本化SQL迁移维护，执行 `python -m pfor_qmt.cli migrate` 后可在数据库客户端直接查看；`python tools/generate_schema_docs.py --check` 检查文档与数据库元数据一致性。
+
+## Web 控制台
+
+工作台按数据查询、期货资料、采集管理、质量运维、系统设置分组，每页聚焦一个流程。新增数据集编辑/复制、维护计划独立保存与执行预览、完整范围统计、独立K线时间窗及资料图表。操作路线见[控制台指南](docs/CONSOLE_GUIDE.md)，视觉约定见[设计规范](docs/CONSOLE_DESIGN.md)。
+
+## Tushare 期货历史
+
+期货资料新增「结算参数」和「主要品种交易周报」，与现有「成交持仓排名」共用多选同步、资料查询、维护任务及CSV/Parquet导出。结算按月份合约选择，周报按品种选择；费率保留原值，周报金额转元并保留原始亿元。详见[接入说明](docs/SETTLEMENT_WEEKLY.md)。
+
+QMT离线时可在「系统设置 → Tushare 账号」新增账号，填写本地Token并检测权限。到「采集执行 → 目录同步」选择Tushare和采集账号，同步期货目录；随后在「证券目录」选择合约并新建数据集，在「采集执行 → 历史回补」下载，到「历史行情」查询图表或导出CSV/Parquet。
+
+多账号共用根目录config.toml。日/周/月线与具体月份合约1/5/15/30/60分钟历史复用现有PostgreSQL表和任务，保留来源不覆盖QMT数据。分钟需要独立权限；主力/连续分钟拼接、实时行情不在本次接入范围。配置与SDK示例见docs/CONFIGURATION.md、docs/API.md。
+
+分钟接口无权限时，在「采集执行 → 历史回补」选择原数据集，将「本次回补周期」仅勾选日线。此选择只作用于新任务，不修改数据集或原任务；已入库日线仍可查询和导出。原任务保留分块与检查点，分钟授权后可定向创建关联重试任务。任务显示的已入库行数不代表所有请求周期均完成。
+
+Tushare历史库现支持日/周/月及1/5/15/30/60分钟。周/月线使用上游结果，保留计算截至日期；未结束周期以not_published标记等待周期结束。顶部切换Tushare后，进入「期货资料」选择交易日历、主力映射、仓单或成交持仓排名，再选交易所与产品/合约，同步任务完成后查询或导出。该页读取本地数据库，无需数据源在线；可从原始任务保存自动维护范围，历史K线数据集也可开启自动更新，同一范围不要重复启用两种方式。
+
+2000积分不包含分钟的独立授权，也不包含Tick文件服务。Tick官方没有API，本项目不提供假下载入口；收到实际CSV样本后再确认导入规则。详细口径见[扩展说明](docs/TUSHARE_EXTENSIONS.md)。
+
+面向股票、行业概念、指数、期货、期权、场内基金、债券的本地行情工作台，覆盖大QMT实际提供的国内品种。基于 [cfquant](https://github.com/95ge/cfquant) 固定提交派生，保留 MIT 许可证；不是上游官方产品。
+
+提供大 QMT 命名管道行情桥、Python SDK、PostgreSQL 历史库、下载任务、CSV/Parquet 导出和原生 Web 工作台。支持不复权日线、1/5 分钟线、当前指数及板块成员，不包含任何交易接口。七类扩展及实机验收状态见 [接入计划](docs/MULTI_ASSET_PLAN.md)，接口支持不代表终端权限或历史数据已经可用。
+
+## 快速启动
+
+主程序需要 Windows、Python 3.12；历史库需要 PostgreSQL 14+。QMT 内嵌组件保持 Python 3.6 语法兼容，独立部署，不向 QMT 安装主程序依赖。
+
+```powershell
+cd D:\国金\pfor-qmt
+py -3.12 -m venv .venv
+.venv\Scripts\python -m pip install -r requirements.lock
+.venv\Scripts\python -m pip install -e . --no-deps
+.venv\Scripts\pfor-qmt key
+.venv\Scripts\pfor-qmt serve
+```
+
+打开 http://127.0.0.1:8766 ，使用 `key` 输出的 API Key 登录。WebSocket 使用本机 8767。端口占用时使用 `serve --port 8876 --ws-port 8877`。同一台机器同一 Windows 会话只运行一个服务。
+
+在「数据源设置」保存 PostgreSQL DSN 并初始化历史库，或使用以下命令。密码仅通过隐藏输入写入本地文件，不放入命令行历史。
+
+```powershell
+.venv\Scripts\pfor-qmt configure --database --qmt-root D:\QMT
+.venv\Scripts\pfor-qmt migrate
+```
+
+统一配置入口是项目根目录 `config.toml`，模板见 [config.example.toml](config.example.toml)。数据库、端口、运行目录、QMT行情连接、API Key及登录密码哈希均由这个文件管理；网页保存也写回此文件，保留注释。
+
+优先级：**显式命令行参数 > `PFOR_QMT_*` 环境变量 > TOML > 默认值**。文件路径通过 `--config` 或 `PFOR_QMT_CONFIG` 指定，默认当前目录的`config.toml`；相对运行目录和QMT路径基于配置文件所在目录解析。环境变量和命令行覆盖只在当前进程生效，不会写回文件，也不会修改系统环境变量。
+
+首次找不到TOML时，会迁移原`runtime/settings.local.json`中的连接、API Key和密码哈希，原JSON保留为备份，后续不再读取。真实`config.toml`已被Git和构建包排除，不要分享或放在公共目录。手工修改后重启服务；修改行情管道配置后需重新准备自有QMT模型并重启终端。
+
+```powershell
+.venv\Scripts\pfor-qmt --config D:\国金\pfor-qmt\config.toml serve
+```
+
+完整配置项和环境变量对应关系见 [配置说明](docs/CONFIGURATION.md)。
+
+## 服务管理
+
+在项目根目录使用 `pfor.ps1`（Windows PowerShell 5.1 / PowerShell 7）：
+
+```powershell
+.\pfor.ps1 start                  # 后台启动，重复执行不会启动第二份
+.\pfor.ps1 status                 # 进程、网页地址及 HTTP/WebSocket 就绪状态
+.\pfor.ps1 stop                   # 停止本项目服务
+.\pfor.ps1 restart                # 停止后重新加载配置并启动
+.\pfor.ps1 logs -Tail 100          # 最近一次启动的标准输出
+.\pfor.ps1 logs -ErrorLog         # 最近一次启动的错误日志
+.\pfor.ps1 logs -Follow           # 持续查看；Ctrl+C 仅结束日志查看
+.\pfor.ps1 help
+```
+
+可从其他目录通过脚本完整路径调用。配置路径按 `-Config`、`PFOR_QMT_CONFIG`、脚本目录的 `config.toml` 选择；相对配置路径基于脚本目录。端口和运行目录复用统一配置及环境覆盖，不另外保存一份配置。每次启动的日志分别保存在运行目录，保留旧日志。就绪状态仅表示Web服务可访问，不代表数据库或QMT数据已经可用。
+
+脚本只管理命令行中配置文件绝对路径匹配的pfor-qmt进程，不停止QMT、PostgreSQL或占用端口的其他应用。此前在前台用相对配置路径或省略`--config`启动的服务，请先在原终端按Ctrl+C，再改用本脚本启动。
+
+`stop`直接结束服务进程，保留已提交数据库事务及任务检查点；重新启动后恢复未完成任务，已发出的QMT请求不能撤销。手工修改配置后执行`restart`。若系统阻止执行脚本，可仅对此次调用使用 `powershell -NoProfile -ExecutionPolicy Bypass -File .\pfor.ps1 status`，将最后的`status`换成所需操作；无需修改系统执行策略。
+
+## 接入 QMT
+
+1. 在设置页检查大 QMT 根目录，退出 QMT 后点击「准备」。
+2. 启动并登录 QMT，等待 `PFOR_MARKET` 模型导入，然后退出。
+3. 点击「启用」，再次启动并登录 QMT，点击「测试行情连接」。
+4. 如果终端没有可唯一识别的模型账户绑定，先在 QMT 为 `PFOR_MARKET` 手工选择账户并保存，再退出并启用。该绑定仅满足终端模型运行要求，不开放交易。
+
+部署只管理 `pfor_qmt_managed/`、`PFOR_MARKET.py`、同名导入包及同名模型节点，修改 XML 前保存备份。不会清理、停用、替换 cfquant 模型，也不会自动退出或登录 QMT。
+
+已导入并启用的模型更新时，只需退出QMT后执行「准备」，再启动登录，无需重复「启用」。期货、期权和分类树需要新版桥；`/source/test`返回`catalog_version: 2`可确认版本。
+
+“行情桥已连接”不代表行情服务器已登录。在设置页点击「检查历史数据」，分别查看快照时间、近30天本地日线和交易日历。历史和日历均为空时，先在QMT手动检查行情连接和日K线；不要直接扩大回补。只读命令为 `.venv\Scripts\python.exe -X utf8 tools/live_acceptance.py`。
+
+## 初次使用
+
+先在行情页顶部「证券与合约目录」勾选需要的类别并点击「同步证券目录」，默认优先期货和期权。支持六家期货交易所、沪深期权、A/B股、国内指数、场内基金、债券及行业概念。后台读取终端当前目录与真实名称，显示进度，支持停止、任务页重试和服务重启恢复。相同或更小范围的重复请求返回当前活动任务；增加类别时需等待原任务完成。只同步资料，不下载全市场历史行情，也不自动删除旧证券。
+
+行情证券、历史查询和数据集成员均可按代码或名称搜索并复选；诊断和单指数映射保留单选。类别、交易所及合约类型可多选，支持本页全选、全选筛选结果、仅看已选和跨页保留；取消选择窗口会还原。全选超过10000项时需缩小范围，QMT行情最多100项。详情按钮查看来源及已获得的原生字段。代码保留大小写与空格，如`cu2610.SF`、`SP a2611&a2701.DF`。已同步目录可在QMT离线时查询。
+
+历史库可同时选择多个合约和周期，图表按单个合约/周期切换；多周期导出分别生成文件。期货资料可多选日历、仓单、排名和映射，选择交易所及产品后批量同步或导出，查询结果按资料页签分别展示。仓单和排名完整字段位于记录详情，可复制原始记录或翻看本页相邻记录。
+
+历史、资料、下载和任务筛选均有「日期范围」快捷菜单：今天、近三天、一周、一/三/六个月、一/二/三年；也可手动修改起止日期。按上海日期计算且含结束日，月/年按日历回退；今天尚未发布的数据可能为空。任务可按状态、类型、来源多选筛选，详情显示固定范围、进度、已入库行数与未确认缺口。
+
+「行业概念」独立展示QMT分类路径及当前成员，可以刷新快照并以成员建立数据集。板块不作为证券，不生成板块K线；成员变更不会自动改写既有数据集或任务。场内基金包括终端基金目录中的ETF和其他基金，ETF保留子类筛选。
+
+指数页选择指数后自动带出名称，优先选用已有板块映射或名称完全匹配的QMT板块；没有精确匹配时需从可搜索的板块下拉框选择，不猜测成分关系。刷新当前成分后可以查看代码与名称，或以该快照创建数据集。分钟线需显式勾选。
+
+行情页订阅后显示证券数量。重新选择证券并再次订阅可切换行情；方形停止按钮退订行情并保留最后显示值，任务推送保持连接。断线时显示等待恢复，连接恢复后重订阅；退出登录会关闭连接，重新登录后需再次订阅。
+
+下载任务页可多选同一来源的数据集和周期后回补，每个数据集执行其已有周期与所选周期的交集；无交集时整批拒绝。批量提交前展示范围，取消不会创建任务；账号及端点始终取自各数据集。留空日期时日线默认一年、分钟线90天。已创建任务保存成员与日期分块，不受之后成员变化影响。QMT默认交易日17:00、Tushare19:00更新；进程必须运行，关机期间到期任务在恢复后补建。
+
+文件导出独立于行情下载队列，QMT请求等待或失败不会阻塞已有数据导出。任务页分别显示行情调度和文件导出的后台错误；下载仍限制为单源单任务。
+
+数据库保存 QMT 原始、不复权 OHLC、量额、可获得的持仓量、结算价及交易日，不换算终端单位。夜盘时间不移动；查询优先按终端交易日，未提供时按上海自然日查询并保留待核验提示，不猜测夜盘归属。期货和期权不请求股票复权因子，调度按数据集实际市场读取日历。当前成分快照只表示观察时点；历史库查询和导出可在QMT离线时使用。
+
+先验证所选资产的短区间日线，当前优先期货和期权，再扩大到分钟线及更多证券。[实机验收步骤](docs/LIVE_ACCEPTANCE.md)提供小样本工具，支持`--codes`自选最多10个证券/合约、`--period 1d/1m/5m`，核对重复回补、SDK分页、数据库及两种文件格式；显式使用`--download`才会创建任务和写入真实数据。分钟验收限制一个交易日，覆盖待核验时仍保留partial。
+
+## 任务质量与运行日志
+
+维护计划支持编辑名称、时间和回读交易日数；数据集自动更新与维护计划不能重复启用。多交易所分别记录调度进度，日历故障不阻塞其他已选市场，恢复后不重复排队。操作、阻塞与恢复均可查日志，详见[维护说明](docs/MAINTENANCE.md)。
+
+任务详情同时显示执行状态和分块质量。「部分完成」表示仍有未解决范围；「待核验」表示已有结果的完整性或交易日归属未确认；「阻塞」表示权限、配置或前置条件不足。不能把已有行数视为整批完成。查看分块的错误码、原因和建议动作后，可仅勾选需要补数的分块重试；新任务保留与原任务的关联，不改写旧记录。未知夜盘归属和交易时段不能靠重复下载解决。
+
+「运行与日志」集中显示队列、待处理任务、最近行情及写入时间、维护范围与任务事件。日志可按来源、级别、日期筛选，详情包含请求范围、校验问题和脱敏异常样本；升级前的任务不补造事件。事件默认保留90天、异常样本30天，数据库不可写时另写运行目录的轮转日志。
+
+在原始目录或采集任务详情中保存维护范围，设置名称、执行时间和回读交易日数。维护仅处理保存的对象，不自动扩大范围；默认QMT 17:00、Tushare 19:00、回读五交易日。可补异常最多自动补数三轮，权限与参数错误不自动重试。停用维护只阻止新调度，已经排队的任务需单独取消。
+
+资料发布时间、分钟逐时段连续性及真实跨交易日维护仍有未完成或未验证项，详见[整改记录](docs/RELIABILITY_PLAN.md)与[验证记录](docs/VERIFICATION.md)。
+
+## 数据新鲜度
+
+只读核验确认有缺口后，可在任务详情点击「预览缺口补数」，确认来源、账号和日期再提交。补数保留原任务证据，完成后重新核验；「关联任务」可在采集、核验、补数之间跳转。未知分钟时段和夜盘问题不会被直接当作缺数下载。
+
+下载任务详情可执行「只读重新核验」，以新任务复查数据库中的覆盖、周期与字段，数据源离线也能运行。分块详情包含规则版本和可疑分钟间隔；原任务与行情保持不变。数据库断开时，「运行与日志」仍可读取本地运行故障。完整规则和外部验收边界见[质量核验](docs/QUALITY_VERIFICATION.md)。
+
+「运行与日志」按已启用的数据集和维护计划逐对象检查，支持来源筛选、代码搜索、分页和详情。日线、映射及日历依据维护时间、对应来源日历和合约存续期给出更新滞后、尚无数据等结论；未纳入维护的归档不报警。分钟时段、夜盘及其他资料发布规则不足时显示具体待核验原因。查询不触发采集，完整口径见[数据新鲜度](docs/FRESHNESS.md)。
+
+## Python SDK
+
+```python
+from pfor_qmt import DataClient, xtdata
+
+client = DataClient.from_config("config.toml")
+xtdata.configure_from_file("config.toml")
+catalog_job = client.sync_catalog(["future", "option"])  # 优先同步期货、期权；省略参数则七类全部同步
+contracts = client.catalog(kind="future", market="SF")
+matches = client.catalog(search="沪深300", kind="index")
+dataset = client.create_dataset("核心指数", ["000300.SH", "000905.SH"], ["1d"])
+job = client.download(dataset["id"], "2026-09-01", "2026-09-14")
+print(client.job(job["id"]))
+page = client.history("000300.SH", limit=500)
+tick = xtdata.get_full_tick(["000300.SH"])
+```
+
+`DataClient` 通过认证 HTTP 接口访问历史库，数值以精确十进制字符串返回。`xtdata` 是本机管道直连接口，需要行情桥在线。订阅回调不得同步调用管道 RPC，应把数据转交队列；自行使用 `xtdata` 的客户端在重连后需要重新订阅。Web 工作台自动恢复订阅。
+
+## 开发与验证
+
+```powershell
+.venv\Scripts\python -m pip install -e '.[dev]'
+.venv\Scripts\python -m pytest -q
+# 仅设置为隔离测试数据库，测试会创建并删除 pfor_qmt_test_* schema
+$env:PFOR_QMT_TEST_DSN = 'postgresql://user:password@127.0.0.1:55436/pfor_test'
+.venv\Scripts\python -m playwright install chromium
+$env:PFOR_QMT_BROWSER_TEST = '1'
+.venv\Scripts\python -m pytest -q
+.venv\Scripts\python -m build
+```
+
+测试没有覆盖率百分比门槛；必须通过交易拒绝、命名隔离、重复入库、任务恢复、调度、导出和界面回归。无测试数据库或浏览器开关时，相应测试会显式跳过，不能据此宣称全部验收通过。
+
+## 发布软件包
+
+`.github/workflows/python-publish.yml` 会在 GitHub Release 发布后构建并检查 wheel 和源码包，同时发布到 PyPI，并把两个文件附加到该 Release。发布前先在 `pyproject.toml` 更新版本号，再创建同名标签，例如版本 `0.1.0` 使用标签 `v0.1.0`。
+
+首次发布到 PyPI 前，在 PyPI 配置 Trusted Publisher：仓库所有者填写 `pbeenigg`，仓库填写 `pfor-qmt`，工作流填写 `python-publish.yml`，环境填写 `pypi`。之后创建并发布 GitHub Release 即可触发；也可以手动运行工作流，但必须填写一个已存在的 Release 标签。
+
+项目结构、接口与状态见 [执行规范](AGENTS.md)、[架构](docs/ARCHITECTURE.md)、[API](docs/API.md)、[兼容矩阵](COMPATIBILITY.md)、[验证记录](docs/VERIFICATION.md)。