Add grid trading GUI design spec

docs/superpowers/specs/2026-07-08-grid-trading-gui-design.md

@@ -0,0 +1,184 @@
+# A股/ETF 网格交易管理 GUI 设计
+
+日期：2026-07-08
+
+## 目标
+
+构建一个本地运行的 Python GUI 个人交易管理软件，用于管理 A股/ETF 的网格交易账户。软件不连接券商、不自动下单，核心价值是把成交记录、持仓成本、网格收益、回本价和每日操作建议统一管理，减少手工表格计算。
+
+第一阶段先实现“每天能用”的本地账本：账户、标的、策略配置、成交录入、持仓表、成本/利润/回本价计算、SQLite 持久化。行情刷新、盘中提醒、图表分析放在后续阶段。
+
+## 已确认决策
+
+- 应用形态：Python 桌面 GUI。
+- 技术路线：PySide6 + SQLite + 分层业务计算模块。
+- 交易市场：A股股票和 ETF。
+- 数据来源：成交手动录入；行情后续半自动刷新。
+- 首屏布局：持仓表优先，左侧导航，顶部账户摘要，中间持仓表，下方选中标的详情。
+- 网格策略：默认模板 + 单标的覆盖。
+- 回本价：同时显示持仓回本价和账户回本价。
+- 使用场景：盘中辅助 + 盘后复盘；第一阶段先做盘后复盘和账本计算。
+
+## 第一阶段范围
+
+第一阶段交付一个可运行的本地桌面应用，包含以下能力：
+
+1. 账户管理
+   - 创建和编辑一个本地账户。
+   - 维护现金余额、初始资金、账户备注。
+   - 账户摘要显示总资产、现金、持仓市值、浮动盈亏、资金使用率。
+
+2. 标的管理
+   - 添加 A股/ETF 标的，字段包括代码、名称、市场、交易单位。
+   - 交易单位默认按 A股一手 100 股处理，可在标的层覆盖。
+   - 为标的绑定默认网格模板，也允许设置单标的覆盖参数。
+
+3. 网格策略配置
+   - 默认模板字段：网格间距、每格金额、底仓目标金额、最大投入金额、最小交易单位。
+   - 单标的覆盖字段：可覆盖模板中的任意策略参数。
+   - 第一阶段仅保存和展示策略参数，不自动生成委托清单。
+
+4. 成交记录
+   - 手动录入买入、卖出成交。
+   - 成交字段包括日期、代码、方向、价格、数量、手续费、印花税、过户费、交易分组、备注。
+   - 交易分组包括底仓、网格、其他，用于区分底仓和网格仓。
+   - 手续费支持自动估算和手动覆盖，费率在设置中可配置。
+   - 支持修改和删除成交，保存后自动重算相关持仓。
+
+5. 持仓表
+   - 每个标的一行，展示代码、名称、当前价格、总持仓、可用数量、底仓数量、网格仓数量、持仓成本、持仓回本价、账户回本价、已实现盈亏、累计网格利润、浮动盈亏。
+   - 第一阶段没有行情源时，当前价格可手动维护；未维护价格时使用最近成交价作为估值参考，并在界面中标记。
+   - A股 T+1 可用数量按交易日期计算：当日买入数量不可卖出，当日卖出会减少可用数量。
+
+6. 数据持久化
+   - 使用本地 SQLite 数据库保存账户、标的、策略、成交、现金流水和应用设置。
+   - 数据库存放在 `data/grid_trading.db`。
+   - 每次启动从数据库恢复状态。
+
+## 非目标
+
+第一阶段不做以下内容：
+
+- 不自动登录券商。
+- 不自动下单。
+- 不接实时行情。
+- 不生成盘中弹窗提醒。
+- 不做复杂图表。
+- 不做多账户同步或云端备份。
+- 不提供投资建议，只做用户规则下的数据计算和提醒基础。
+
+## 架构
+
+采用分层结构，避免 GUI 代码和交易计算混在一起：
+
+- `app`：应用入口、窗口初始化、主题和全局状态。
+- `ui`：PySide6 界面，包括主窗口、持仓表、成交录入弹窗、标的管理、策略设置。
+- `services`：业务服务，包括成交保存、持仓重算、账户摘要、费用估算。
+- `domain`：核心交易模型和计算逻辑，尽量不依赖 PySide6，便于单元测试。
+- `repositories`：SQLite 读写封装。
+- `config`：默认费率、数据库路径和应用设置。
+
+GUI 只负责展示和收集输入；所有计算通过 service 调用 domain 模块完成。这样后续添加行情、图表和导入导出时，不需要重写持仓计算。
+
+## 数据模型
+
+核心表：
+
+- `accounts`：账户基础信息、初始现金、当前现金。
+- `instruments`：标的信息，包括代码、名称、市场、交易单位、手动价格。
+- `strategy_templates`：默认网格模板。
+- `instrument_strategy_overrides`：单标的策略覆盖。
+- `trades`：成交记录。
+- `cash_ledger`：现金流水，包括初始入金、成交资金变化、手工调整、分红。
+- `app_settings`：手续费规则和界面设置。
+
+持仓表不作为主数据源保存，而是由成交和现金流水派生计算。必要时可以做只读缓存，但重算结果必须能从原始记录恢复。
+
+## 计算口径
+
+费用：
+
+- 买入成交成本 = 成交金额 + 买入费用。
+- 卖出净收入 = 成交金额 - 卖出费用。
+- 费率可配置；录入成交时允许用户覆盖实际费用。
+
+持仓成本：
+
+- 底仓、网格、其他三个交易分组分别维护移动平均成本。
+- 总持仓 = 三个分组的剩余数量合计。
+- 总持仓成本 = 三个分组的剩余成本合计。
+- 持仓成本价 = 总持仓成本 / 总持仓数量。
+
+已实现盈亏：
+
+- 卖出时按对应交易分组的移动平均成本结转成本。
+- 已实现盈亏 = 卖出净收入 - 卖出结转成本。
+- 累计网格利润只统计交易分组为网格的已实现盈亏。
+
+回本价：
+
+- 持仓回本价 = (当前剩余持仓成本 - 累计网格利润) / 当前总持仓数量。
+- 账户回本价 = 该标的累计净投入 / 当前总持仓数量。
+- 累计净投入 = 历史买入总支出 + 相关费用 - 历史卖出净收入 - 分红及其他现金流入。
+- 当前总持仓数量为 0 时，回本价显示为空，并展示历史已实现盈亏。
+
+估值：
+
+- 持仓市值 = 当前价格 * 当前总持仓数量。
+- 当前价格优先使用手动维护价格；没有手动价格时使用最近成交价，并显示“估值价来自最近成交”。
+- 浮动盈亏 = 持仓市值 - 当前剩余持仓成本。
+
+## 主界面
+
+主窗口采用持仓表优先布局：
+
+- 左侧导航：账户总览、持仓管理、成交记录、网格策略、设置。
+- 顶部摘要：总资产、现金、持仓市值、浮动盈亏、资金使用率。
+- 操作栏：刷新、录入成交、添加标的、策略设置、搜索。
+- 中央持仓表：展示所有标的的核心指标。
+- 底部详情区：展示选中标的的最近成交、分组持仓、策略参数和计算说明。
+
+第一阶段的“刷新”只从数据库重算，不调用行情接口。
+
+## 错误处理
+
+- 成交数量必须是交易单位的整数倍，除非标的显式允许非整手。
+- 卖出数量不能超过该标的可卖数量。
+- 价格和费用不能为负数。
+- 删除或修改历史成交后，系统按时间顺序重算该标的全部持仓。
+- 数据库写入失败时显示错误弹窗，并保留用户当前输入。
+- 计算出现除零或无持仓时，界面显示空值而不是异常。
+
+## 测试策略
+
+第一阶段重点测试核心计算，而不是 GUI 细节：
+
+- 单元测试覆盖买入、卖出、费用、移动平均成本、已实现盈亏、累计网格利润。
+- 单元测试覆盖持仓回本价和账户回本价。
+- 单元测试覆盖 T+1 可用数量。
+- 仓储测试覆盖 SQLite 初始化、插入、更新、删除和重启恢复。
+- 一个轻量 GUI 冒烟测试验证主窗口可启动。
+
+## 验收标准
+
+第一阶段完成时，应满足：
+
+- 可以启动桌面应用。
+- 可以创建账户、添加标的、配置默认网格模板和单标的覆盖。
+- 可以手动录入、修改、删除买卖成交。
+- 持仓表能正确展示数量、成本、盈亏、网格利润和两种回本价。
+- 关闭并重新打开应用后，数据仍然存在。
+- 核心计算测试通过。
+
+## 后续阶段
+
+第二阶段：接入 A股/ETF 行情源，支持手动刷新和定时刷新，生成买卖档位和今日委托建议。
+
+第三阶段：加入图表，包括成本变化曲线、累计网格收益、账户盈亏和资金使用率。
+
+第四阶段：加入导入导出、备份恢复、券商导出文件解析和更完整的复盘报表。
+
+## 参考
+
+- Qt for Python / PySide6 官方文档：https://doc.qt.io/qtforpython-6/
+- AKShare 股票数据文档：https://akshare.akfamily.xyz/data/stock/stock.html