docs: design grid level suggestions

docs/superpowers/specs/2026-07-09-grid-level-suggestions-design.md

@@ -0,0 +1,106 @@
+# 网格档位建议设计
+
+日期：2026-07-09
+
+## 目标
+
+在 GUI 中为选中的 A股/ETF 标的生成网格档位表，帮助用户根据腾讯接口刷新的现价和现有策略模板，快速看到每一档的买入价、建议股数、实际投入、卖出价和预计单轮毛利润。
+
+该功能只做计算和展示，不自动下单，不自动创建成交记录，也不保存生成结果。
+
+## 已确认口径
+
+- 买入档位使用现有策略模板里的 `网格间距`，按百分比逐档递减。
+- 卖出价也使用同一个 `网格间距`，即买入后上涨同样百分比作为该档卖出价。
+- 买入金额使用策略模板里的 `每格金额`。
+- 现价只来自腾讯行情快照；没有现价时不生成档位，并提示先刷新行情。
+- 建议股数按标的交易单位向下取整，默认 100 股一手。
+- 预计单轮毛利润不扣手续费，先保持和用户截图一致。
+
+## 计算公式
+
+设：
+
+- `current_price`：腾讯行情现价
+- `spacing`：策略模板网格间距，例如 3% = `0.03`
+- `amount_per_grid`：策略模板每格金额
+- `lot_size`：标的交易单位
+- `level`：档位，从 1 开始
+
+逐档计算：
+
+```text
+第1档买入价 = current_price * (1 - spacing)
+第N档买入价 = 第N-1档买入价 * (1 - spacing)
+
+建议买入股数 = floor(amount_per_grid / 买入价 / lot_size) * lot_size
+实际投入 = 买入价 * 建议买入股数
+卖出价 = 买入价 * (1 + spacing)
+预计单轮毛利润 = (卖出价 - 买入价) * 建议买入股数
+```
+
+价格按现有 `price()` 规则保留两位小数，金额按现有 `money()` 规则保留两位小数。
+
+如果金额不足以买入一个交易单位，该档股数为 0，实际投入和预计利润为 0。
+
+## 界面设计
+
+在主窗口下方选中标的区域新增“网格档位”表，列为：
+
+```text
+档位 / 买入价 / 买入金额 / 建议买入股数 / 实际投入 / 卖出价 / 预计单轮毛利润
+```
+
+表格随选中标的变化自动刷新。点击“刷新行情”后，持仓表和网格档位表一起刷新。
+
+第一版提供一个非持久化档数输入，默认 10 档。用户改档数后即时重算，不写入 SQLite。
+
+## 代码结构
+
+新增独立的领域计算模块：
+
+- `src/grid_trading/domain/grid_levels.py`
+  - `generate_grid_levels(...)`
+  - 只依赖 Decimal 和领域模型，便于单元测试。
+
+扩展领域模型：
+
+- `GridLevelSuggestion`
+  - `level`
+  - `buy_price`
+  - `buy_amount`
+  - `suggested_quantity`
+  - `actual_investment`
+  - `sell_price`
+  - `estimated_gross_profit`
+
+扩展服务层：
+
+- `TradingService.get_grid_level_suggestions(instrument_id, levels=10)`
+  - 获取当前持仓摘要中的现价。
+  - 获取默认策略模板。
+  - 获取标的交易单位。
+  - 没有现价时返回空列表，由 UI 显示提示。
+
+## 错误处理
+
+- 没有选中标的：档位表清空。
+- 没有腾讯现价：档位表清空并显示“请先刷新行情”。
+- 网格间距、每格金额或交易单位无效：服务层抛出可读错误，UI 弹窗提示。
+- 档数最小为 1，最大为 100，避免生成过多行影响界面。
+
+## 测试策略
+
+- 单元测试覆盖百分比递减买入价。
+- 单元测试覆盖建议股数按交易单位向下取整。
+- 单元测试覆盖卖出价和预计单轮毛利润。
+- 服务测试覆盖有现价时生成档位、无现价时返回空列表。
+- GUI 冒烟测试覆盖“网格档位”表存在，并能在 offscreen 模式构造。
+
+## 非目标
+
+- 不生成真实委托。
+- 不自动写入成交记录。
+- 不扣除手续费计算净利润。
+- 不做单标的策略覆盖编辑。
+- 不持久化每次生成的档位表。