A-pi 使用与运维说明书
A-pi 是使用真实 Tushare 日线开展因子研究、历史回测、风险检查和纸面交易的工作台，不是券商终端。研究流程通过、回测收益或统计指标都不保证未来盈利。页面状态以当前服务和数据返回为准；不可用、过期或等待状态不能当作正常数据。
1. 启动、登录与全局操作
- 桌面端打开后会连接本机 Python 服务；等待启动页完成，再进入登录页。网页部署则先启动后端服务，再访问部署地址。
- 使用管理员创建的账户或有效邀请码注册。登录时可选择“记住此设备 7 天”；启用双重验证的账户需要验证码或未使用的恢复码。恢复码只展示一次，应离线保存，不要发到聊天或工单。
- 侧栏提供“组合总览、因子研究、因子挖掘、回测实验、风险控制、纸面交易”六个页面。顶部行情条可暂停滚动；搜索框可查股票、策略和页面；铃铛打开本机通知中心；用户菜单进入账户操作；“界面主题”支持浅色、深色和跟随系统。
- 顶部状态条区分 Python 服务与行情数据探针状态。点击“连接详情”可查看 Python、Tushare、SQLite、行情日期和纸面调度状态。服务在线不等于行情已更新。
2. 组合总览
- 市场概览展示上证、深证、创业板指数、两市成交及涨跌数量。具体日期、来源和实时/缓存状态以页面标记为准。
- 指标卡展示组合净值、年化收益、最大回撤和年化换手；数字依赖所选回测和当前可用数据，并非收益承诺。
- “净值走势”可切换日期范围并查看图表数据；“当前暴露”展示纸面组合持仓及现金等配置；下方包含“持仓与信号”和“研究护栏”。右侧汇总纸面账户、今日运行和风险观察。
- “导出状态详情”导出当前界面显示的回测版本、纸面账户、研究门禁与风险状态（JSON），不包含登录凭据；“运行回测”进入回测流程。真实行情不可用时不要以旧状态推断最新情况。
3. 因子研究
- 查看研究统计、因子注册表和分类筛选。因子值、覆盖、样本量、交易日与数据来源应结合阅读；“等待标签成熟”或“覆盖不足”不是零 IC，也不是通过。
- 三大财务报表区域展示接口返回的利润表、资产负债表和现金流量表数据。财务字段按公告可得日期使用；报告期结束日不能代替公告日。
- “上线后样本外 IC 日更”按页面说明监控已冻结信号，标签成熟后才计算 IC；选择 1/5/10/20 日标签周期并点击“刷新监控状态”查看。数据不足、覆盖不足和接口失败都应按原状态处理，不要手工补成有效样本。
- 行业 PIT 覆盖只从真实观察快照积累日起使用。历史行业信息缺少可靠可得时间时会保持禁用；不能把当前行业分类回填为历史 PIT。
4. 因子挖掘
- 先查看研究边界和密封快照状态，再选择“基础模板”并点击“载入模板”，或在表达式 DSL 中编辑受限表达式。模板只填入表达式，不代表已注册、已验收或可用于组合。
- 随机种子、进化代数、每代种群和候选上限共同决定探索范围。一次性密封验收有固定测试宇宙和研究预算，运行前检查窗口、N_tested、剩余预算和权限。
- “运行遗传搜索”生成候选；“评估此表达式”用于诊断。只有获得真实数据并通过相应 PIT、样本量和统计门槛的结果才可按页面规定提升。不可通过反复搜索或查看密封结果择优。
- 密封评估是不可重复的验收操作。预算耗尽时查看台账和归档选项；归档会保留审计记录，不会让旧失败变成通过，也不应为方便而绕过门禁。
5. 回测实验
- 在配置区设置策略、股票池（包括可用的历史指数成分选项）、起止日期、初始资金、调仓频率与交易成本。成本选项按当前页面提供的佣金、印花税、过户费及滑点/冲击模型生效；对比实验时保持口径一致。
- 检查训练、验证、测试区间及 embargo 信息后再提交。长任务会显示进度；页面超时或刷新不等于服务端任务已经停止。先查看任务状态和研究台账，不要重复提交相同任务。
- 结果区结合净值曲线、基准、收益、回撤、换手、成交和成本阅读；敏感性扫描、样本外摘要、实验对比和治理状态各自回答不同问题。不要只按单一 Sharpe 或累计收益挑选参数。
- 报告绑定所用数据和配置。历史固定股票池可能带来选择偏差；历史成分接口、上市时间过滤或数据覆盖不足时，按页面披露的范围解释结果。
6. 风险控制
- 风险限额展示组合检查结果；“待处理提醒”可查看来源和行情日期，确认后可关闭提醒。关闭只是隐藏/确认该条提醒，不会更改风险数据或放宽交易限制。
- 严格 PIT 协方差组合优化仅在所需历史数据和可得时间证明满足门槛时开放。输出是研究建议，不会自动修改纸面策略、生成委托或切换实盘。
- 历史 VaR、ES、相关性和压力窗口属于回顾性统计，不是实时预测、止损保证或风险为零证明。
7. 纸面交易
- 页面展示纸面权益、现金、持仓数量、行情质量和委托生命周期。委托状态按服务端记录查看；没有成交时先检查调仓跟踪、数据质量、限制价、风控拒绝原因和目标持仓变化。
- 新建委托时明确选择买入或卖出并填写证券和数量，再检查确认信息。取消、关闭窗口或按 Esc 不应被理解为反向委托。
- 纸面策略信号使用已确认的收盘日线；模拟成交只能使用后续交易日可执行价格，不使用信号日收盘价立即成交。涨跌停、停牌、T+1、整手和风险规则可能使委托延期或拒绝。
- 所有订单仅写入本地模拟账本，不会发送给券商。不要将纸面收益或成交描述为实盘结果。自动循环的时间窗口、交易日判断、重试和幂等状态以当前 Python 服务及“连接详情/今日运行”显示为准；桌面离线或服务停止期间不能保证后台执行。
8. 账户与安全
- 账户菜单中的安全设置可管理密码、双重验证、设备会话及恢复码；管理员用户管理功能仅对获授权管理员开放。管理员创建账户时应使用系统要求的首次改密流程。
- 研究、因子和纸面数据按账户隔离。多人远程使用应部署在受控 HTTPS 入口后，使用不同账户；不要共享登录会话或把整个 data 目录复制给其他人。
- 不得向聊天发送密码、TOTP 验证码、恢复码、会话令牌、Tushare Token 或认证密钥。外部通知未配置并测试前，不会自动向外发送账户信息。
9. 运维与故障排查
- 工作台打不开或停在启动页：确认本机 Python 服务进程和监听端口可用；桌面启动器提示 API 版本不兼容时，使用项目提供的受控重启流程更新后端，再重新打开客户端。
- 服务在线但行情不可用：点击“连接详情”，检查 Tushare Token 配置、权限、网络/DNS、数据探针日期和错误提示。服务健康检查成功不代表每个行情接口都可用。
- 显示旧数据或工作区生成中：观察工作区状态与最后更新时间；等待当前构建结束或查看明确错误。不要用静态数字覆盖数据日期，也不要在旧任务未终止时重复提交。
- 页面仍显示旧版：新静态资源按版本哈希发布，先刷新页面；必要时使用 Ctrl+F5。若仍旧，核对服务实际提供的 release 与桌面/浏览器访问地址，避免连接到另一份旧服务。
- Redis 队列任务不动：确认 Redis 服务、队列配置以及独立 worker 都在线。Redis 单独启动不代表有任务消费者；本机默认队列方式以服务当前配置为准。
- 备份与恢复：通过运维状态核对数据库、日志和备份位置，并按部署文档执行权限控制和恢复演练。不要直接编辑生产 SQLite 数据库，也不要用重置目录代替恢复。
服务器远程访问应使用 HTTPS 反向代理与可信代理配置，不要把 Python API 端口直接暴露到公网。更新前确认目标进程、配置和数据备份；重启只影响本机服务，不会自动修复 Tushare 权限或缺失历史数据。
10. 数据与能力边界
- 工作台以真实 Tushare 数据及本机持久化记录为依据；接口失败时应显示不可用、缓存或覆盖不足，不应合成行情。
- 日线模拟不能还原分钟级路径、盘口深度、真实排队和券商成交；费用与冲击模型只是估算。
- 历史回测、密封验收、样本外 IC 和风险统计各有不同用途。通过研究流程不等于策略有效，更不构成投资建议。
- 严格 PIT 行业归因、历史覆盖、特征库和模型能力只在界面/接口给出真实数据与当前状态时成立；“等待数据”“覆盖不足”“不可用”不得被解释成已完成。
- 当前系统用于研究与纸面模拟，没有真实券商下单链路。不得自动切换实盘、绕过研究门禁或为制造成交而更改核心策略参数。