feat: 优化界面并补充网格成交分析

README.md

@@ -1,73 +1,216 @@
-# Grid Trading
+# Grid Trading：本地网格交易管理器
 
-本项目是一个本地运行的 Python GUI 网格交易管理工具，第一阶段聚焦 A股/ETF 的账户、标的、手工成交、持仓成本、网格收益和回本价计算。
+一个使用 Python 和 PySide6 开发的本地桌面工具，用于管理 A 股、ETF 的账户、标的与手工成交，并辅助计算持仓成本、网格收益、回本价和网格档位。
 
-## 第一阶段功能
+> 本项目只提供交易记录与策略辅助功能，不会连接券商账户，也不会自动下单。所有计算结果仅供参考，不构成投资建议。
 
-- 创建/编辑本地账户和初始资金。
-- 添加 A股/ETF 标的，维护交易单位。
-- 配置默认网格策略模板。
-- 手动录入、编辑、删除买入/卖出成交。
-- 自动计算持仓数量、T+1 可用数量、持仓成本、已实现盈亏、累计网格利润、持仓回本价、账户回本价。
-- 点击“刷新行情”从腾讯接口获取实时价格，并用实时价更新持仓市值和账户摘要。
-- 根据刷新后的现价和默认网格策略，生成选中标的的网格档位建议。
-- 使用 SQLite 本地保存数据，默认路径为 `data/grid_trading.db`。
+## 功能特性
 
-## 行情说明
+- **账户概览**：展示账户权益、现金、持仓市值、浮动盈亏和资金使用率。
+- **标的管理**：维护股票或 ETF 的代码、名称、市场、交易单位及零股规则。
+- **成交管理**：手工录入、编辑和删除买卖记录，并区分底仓、网格仓和其他仓位。
+- **费用估算**：按内置费率估算佣金、印花税和过户费，估算后仍可手工调整。
+- **持仓分析**：计算总持仓、T+1 可用数量、剩余成本、已实现盈亏、浮动盈亏及网格利润。
+- **回本价计算**：同时提供持仓回本价与账户回本价，便于观察网格收益对成本的影响。
+- **实时行情**：异步获取腾讯行情，刷新过程中不会阻塞主界面。
+- **网格建议**：根据实时价格和默认策略，生成最多 100 档的买入价、建议数量、卖出价与预计毛利润。
+- **待卖网格**：按批次展示尚未卖出的网格买入及其目标卖出价、当前状态。
+- **成交配对**：使用 FIFO（先进先出）将网格卖出与历史网格买入配对，一笔卖出可拆分匹配多笔买入。
+- **本地存储**：账户、标的、策略和成交数据均保存在 SQLite 数据库中。
 
-行情刷新使用腾讯接口：
+## 技术栈
 
-```text
-http://qt.gtimg.cn/q=<symbol>
+- Python 3.11+
+- PySide6
+- SQLite
+- pytest
+
+## 快速开始
+
+### 1. 进入项目目录
+
+```powershell
+cd Grid_Trading
 ```
 
-例如 `000001` 会自动转换为 `sz000001`，`600000` 会自动转换为 `sh600000`。
+请先下载或克隆项目，再进入项目根目录。
 
-实时行情只保存在当前程序内存中，用于显示现价、持仓市值、浮动盈亏、总资产和资金使用率；不会写入 SQLite。成交录入里的价格只作为成交价保存，不会作为现价兜底。关闭软件后再次打开，需要重新点击“刷新行情”。
+### 2. 创建虚拟环境并安装依赖
 
-## 网格档位说明
-
-选中标的后，底部“网格档位”表会根据腾讯现价和默认策略模板生成建议：
-
-- 买入价按 `现价 * (1 - 网格间距)` 逐档向下递减。
-- 卖出价按 `买入价 * (1 + 网格间距)` 计算。
-- 建议买入股数按标的交易单位向下取整。
-- 预计单轮毛利润不扣手续费，生成结果只用于展示，不会写入成交记录或 SQLite。
-
-## 待卖网格说明
-
-底部“待卖网格”表会展示尚未被网格卖出抵消的网格买入批次，包括买入价、剩余股数、建议卖出价、预计毛利润、当前价和状态。网格卖出按时间顺序 FIFO 抵消最早的网格买入；建议卖出价按 `买入价 * (1 + 网格间距)` 计算。
-
-## 开发环境
+Windows PowerShell：
 
 ```powershell
 python -m venv .venv
 .\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
 python -m pip install -e ".[dev]"
-pytest
 ```
 
-## 启动
+macOS / Linux：
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+### 3. 启动程序
 
 ```powershell
 python -m grid_trading.app
 ```
 
-也可以指定数据库路径：
+安装后也可以使用命令行入口：
+
+```powershell
+grid-trading
+```
+
+默认数据库位置为 `data/grid_trading.db`。如需使用其他数据库文件：
 
 ```powershell
 python -m grid_trading.app --db data/dev.db
 ```
 
-## 验证
+首次启动时，程序会自动创建：
+
+- 初始资金为 `0` 的“默认账户”；
+- 间距为 `3%`、每格金额为 `5000` 元的“默认网格模板”；
+- 数据库及所需数据表。
+
+## 基本使用流程
+
+1. 点击“账户设置”，填写账户名称和初始资金。
+2. 点击“添加标的”，填写证券代码、名称、市场和交易单位。
+3. 点击“策略设置”，调整网格间距、每格金额等参数。
+4. 点击“录入成交”，选择买卖方向、仓位分组并填写实际成交信息。
+5. 点击“刷新行情”，获取现价并更新持仓市值、浮动盈亏和账户摘要。
+6. 在持仓表中选择一个标的，查看“网格档位”“待卖网格”“配对明细”和“最近成交”。
+
+## 行情说明
+
+行情数据来自腾讯接口：
+
+```text
+http://qt.gtimg.cn/q=<symbol>
+```
+
+程序会根据六位证券代码推断交易所前缀，例如：
+
+| 输入代码 | 请求代码 |
+| --- | --- |
+| `000001` | `sz000001` |
+| `600000` | `sh600000` |
+| `510300` | `sh510300` |
+| `430047` | `bj430047` |
+
+需要注意：
+
+- 行情刷新需要网络连接，单次请求超时时间为 5 秒，失败后会自动重试一次。
+- 行情快照只保存在当前进程内存中，不会写入 SQLite。
+- 重新启动程序后，需要再次点击“刷新行情”。
+- 未刷新行情时，不使用手工价格或最近成交价代替现价，因此市值、浮动盈亏和网格档位可能为空。
+
+## 计算口径
+
+### 持仓与盈亏
+
+- 买入成本 = 成交金额 + 交易费用。
+- 卖出净收入 = 成交金额 - 交易费用。
+- 同一仓位分组内的卖出成本按移动平均成本释放。
+- 已实现盈亏 = 卖出净收入 - 被释放的持仓成本。
+- 网格利润只统计“网格”分组的已实现盈亏。
+- T+1 可用数量会扣除计算当日的买入数量；卖出数量不得超过可用数量，也不得超过对应分组的持仓数量。
+- 修改或删除历史成交后，程序会重新校验后续成交，避免形成负持仓。
+
+### 回本价与账户摘要
+
+- 持仓回本价 =（剩余持仓成本 - 已实现网格利润）/ 当前持仓数量。
+- 账户回本价 = 标的累计净投入 / 当前持仓数量。
+- 账户权益 = 现金 + 持仓市值。
+- 资金使用率 = 持仓市值 /（持仓市值 + 非负现金）；现金为负时最高显示为 100%。
+
+### 网格档位
+
+第 1 档买入价按下式计算，之后逐档复合递减：
+
+```text
+买入价 = 上一档参考价 × (1 - 网格间距)
+卖出价 = 买入价 × (1 + 网格间距)
+建议数量 = 每格金额 ÷ 买入价，并按交易单位向下取整
+```
+
+档位表中的“预计单轮毛利润”不扣除交易费用，且建议结果只用于展示，不会自动生成成交记录或下单。
+
+### 待卖网格与配对明细
+
+- 只有“网格”分组的成交参与待卖批次和配对计算。
+- 网格卖出按照成交日期和记录顺序，优先抵消最早的网格买入。
+- 待卖批次状态包括“未刷新行情”“未到价”和“可卖”。
+- 配对明细展示历史买卖的对应关系和毛利润，不扣除费用。
+
+## 默认费用参数
+
+点击成交窗口中的“估算费用”时，程序使用以下默认参数：
+
+| 项目 | 默认值 | 说明 |
+| --- | ---: | --- |
+| 佣金 | 0.025% | 最低 5 元，买卖双向收取 |
+| 印花税 | 0.05% | 仅卖出时收取 |
+| 过户费 | 0.001% | 买卖双向收取 |
+
+不同券商、市场和交易品种的实际费用可能不同，请以实际交割单为准，并在保存成交前手工修正。
+
+## 数据与隐私
+
+- 默认数据文件：`data/grid_trading.db`
+- 账户、成交和策略数据仅存放在本机；刷新行情时只会向腾讯行情接口发送证券代码。
+- `data/*.db`、`data/*.sqlite` 和 `data/backups/` 已在 `.gitignore` 中忽略。
+- 建议定期备份数据库文件；复制数据库前请先退出程序，避免备份到尚未提交的写入状态。
+
+## 项目结构
+
+```text
+Grid_Trading/
+├── src/grid_trading/
+│   ├── app.py                 # 命令行入口
+│   ├── config.py              # 默认路径与费用配置
+│   ├── domain/                # 数据模型、持仓和网格计算
+│   ├── market/                # 腾讯行情适配
+│   ├── services/              # 业务编排与校验
+│   ├── storage/               # SQLite 数据库与仓储层
+│   └── ui/                    # PySide6 主窗口、对话框与格式化
+├── tests/                     # 自动化测试
+├── docs/                      # 设计说明与开发计划
+├── data/                      # 本地数据库目录
+└── pyproject.toml             # 项目及依赖配置
+```
+
+## 测试
+
+运行完整测试：
 
 ```powershell
 pytest -v
-python -m grid_trading.app --help
 ```
 
-如果只想确认 GUI 能构造起来，不打开真实窗口，可以运行测试里的 offscreen smoke：
+只验证界面可在无显示环境下正常构造：
 
 ```powershell
 pytest tests/test_ui.py -v
 ```
+
+检查命令行参数：
+
+```powershell
+python -m grid_trading.app --help
+```
+
+## 当前限制
+
+- 当前定位为单机、单用户的手工交易管理工具。
+- 不包含券商登录、自动下单、条件单或实盘同步功能。
+- 行情接口不是正式授权的数据服务，其可用性、实时性和准确性不作保证。
+- 网格建议未考虑手续费、滑点、涨跌停、停牌和流动性等实际交易约束。
+- 使用本项目产生的任何交易决策与风险均由使用者自行承担。