feat: 迭代03-05 交易记录接入、行情实时、QMT连接配置、data store 标准化
- R-004 QMT连接配置：多配置管理 + 会话头部快捷切换（03-QMT连接配置） - R-005 WS盘中价格实时更新：服务端中转+缓存+前端轮询（04-WS盘中价格实时更新） - R-006 策略数据 JSON data store 标准化（store.json/market.json/schema.json） - R-007 交易记录接入：当日订单+成交单表合并（委托主行+展开成交明细）、时间段查询（今日/本周/本月+手动起止）、费用计算（佣金费率万m_dCommission+最低5元、印花税卖出万5、过户费双向万0.1） - 架构治理：api 按领域拆分、component 目录、QmtHealthMonitor
This commit is contained in:
@@ -9,7 +9,8 @@
|
||||
|
||||
| 编号 | 约束说明 | 添加日期 | 生效状态 | 失效日期 | 最后一次变更描述 |
|
||||
|---|---|---|---|---|---|
|
||||
| （待添加） | | | | | |
|
||||
| UI约束-001 | 会话头部 QMT 连接切换 chip：紧凑形态 `QMT: <激活配置名> ▾`，与 PTC 模式标签并排；下拉菜单列出全部配置（当前激活项勾选标记），点选即激活；操作结果用顶部轻提示反馈（成功绿/失败红，约 3s 消失，沿用现有 Toast 体系） | 2026-08-29 | 生效 | - | R-004 定稿（2026-08-29）：Q9/Q10 确认的头部控件形态 |
|
||||
| UI约束-002 | 设置页「QMT 连接配置」子 tab：与「通用设置 / 策略分组」并列的第三个子 tab；配置以**卡片形式**展示（自适应网格 minmax(260px,1fr)，激活卡片绿色描边）：卡片含名称 + 激活/默认徽标 + HTTP 地址 + 行内操作（激活 / 设为默认 / 编辑 / 测试连接 / 删除）+ 新增/编辑表单（纵排两字段）；删除沿用现有确认弹窗模式，删除最后一条时给出禁止提示；超时不设输入框（Q5）；长文本（地址/错误信息）单行省略 + 悬停看全文，组件设 minWidth:0 防撑行 | 2026-08-29 | 生效 | - | 变更（2026-08-29 老师反馈）：列表形式改卡片形式，约束组件宽度、长文本省略不换行；原定稿：设置页子 tab 形态沿用现有设置交互体系 |
|
||||
|
||||
<!-- 示例条目（确认格式后删除）：
|
||||
| UI约束-001 | 示例：求签页面必须保持单屏完整，不出现滚动 | 2026-08-26 | 生效 | - | 讨论确认：移动端优先，避免滚动打断仪式感 |
|
||||
|
||||
@@ -13,6 +13,9 @@
|
||||
| 产品约束-002 | 分仓通过「持仓标签」体系实现：在全量持仓之上，用不同标签对持仓进行逻辑分组，每个标签展示其下的仓位汇总（数量/市值/盈亏/占比） | 2026-08-27 | 生效 | - | 讨论确认（R-002）：老师要求「分不同的持仓标签，各自有多少仓位」 |
|
||||
| 产品约束-004 | 删除持仓策略时，该策略下已分配的份额自动回到「未分配」，数据不丢失（删除前需弹窗确认） | 2026-08-28 | 生效 | - | R-003 O3 定稿（2026-08-28）：删除策略 = 份额回未分配 + 弹窗确认 |
|
||||
| 产品约束-003 | 持仓标签可自定义、可增删改；标签维度候选包括策略/用途/风险等级等（具体维度待讨论确认） | 2026-08-27 | 生效 | - | 讨论确认（R-002）：标签体系需支持自定义，维度待细化 |
|
||||
| 产品约束-005 | QMT 连接配置多配置管理：设置页「QMT 连接配置」子 tab 维护多个连接配置（名称 + HTTP 地址，增/删/改/查）；一次只能激活一个，激活配置为当前生效连接；默认 = 插件启动时自动激活的配置（运行中手动激活其他配置立即生效，重启回到默认）；测试连接为手动操作（请求 /health 返回可达性与延迟，激活不强制先测）；删除边界：删除激活配置自动切换到默认，删除默认配置则默认标记转移到列表第一条并激活之，禁止删除最后一条 | 2026-08-29 | 生效 | - | R-004 定稿（2026-08-29）：Q1-Q6/Q8 逐条确认（不迁移宿主配置、超时不纳入表单） |
|
||||
| 产品约束-007 | 3 个监控表格（全部持仓 / 手动做T / 网格超市）展示**盘中现价**：现价列显示 lastPrice，红涨绿跌着色（对比昨收），价格变化轻微高亮；本期仅现价一项实时数据 | 2026-08-31 | 生效 | - | R-005 定稿（2026-08-31）：老师确认现价列 + 涨跌色 + 变化高亮 |
|
||||
| 产品约束-006 | QMT 连接会话头部快捷切换：会话窗口顶栏（PTC 模式标签旁）常驻下拉控件（chip 显示 `QMT: <激活配置名>`），点开列出全部配置（激活项勾选），点选即激活并轻提示反馈；头部控件仅做切换，配置管理（增删改/测试连接/默认标记）仍在设置页子 tab | 2026-08-29 | 生效 | - | R-004 定稿（2026-08-29）：Q9/Q10 确认（入口=会话头部 PTC 旁，菜单仅切换激活） |
|
||||
|
||||
<!-- 示例条目（确认格式后删除）：
|
||||
| 产品约束-001 | 示例：求签功能必须保证抽取结果的不可预测性 | 2026-08-26 | 生效 | - | 讨论确认：为保证公平性，抽取必须不可预测 |
|
||||
|
||||
@@ -11,11 +11,16 @@
|
||||
|---|---|---|---|---|---|
|
||||
| 技术约束-002 | 分仓管理采用「全量持仓 + 标签」模型：持仓数据为账户真实持仓（来自数据源适配器），标签为逻辑分组元数据（独立于持仓存储，可增删改），聚合视图按标签汇总仓位 | 2026-08-27 | 生效 | - | 讨论确认（R-002）：全量持仓为基础，标签体系做逻辑分仓 |
|
||||
| 技术约束-001 | 行情/交易数据源必须通过统一接口抽象（定义统一的数据模型与操作接口），实现层为具体数据源适配器；当前限定实现 QMT Bridge 适配器，未来可新增其他行情/交易接口适配器，业务层不感知具体数据源 | 2026-08-27 | 生效 | 2026-08-27 | 变更（2026-08-27 R-002 讨论）：原为「QMT Bridge MCP 适配器」，修正为**直接调用 QMT Bridge RESTful 接口**（http://192.168.3.43:8610），MCP 仅作为 Agent 侧封装层，插件侧直连 REST |
|
||||
| 技术约束-003 | QMT Bridge 数据源通过其 RESTful HTTP 接口接入（基础地址 http://192.168.3.43:8610，OpenAPI v3 规范），不经过 MCP 层；MCP 是给 Agent 用的封装，插件内部直连 REST | 2026-08-27 | 生效 | - | 讨论确认（R-002 第 7 轮）：老师指出 MCP 是给智能体用的，插件应直连同一服务端口的 RESTful 接口 |
|
||||
| 技术约束-003 | QMT Bridge 数据源通过其 RESTful HTTP 接口接入（基础地址 http://192.168.3.43:8610，OpenAPI v3 规范），不经过 MCP 层；MCP 是给 Agent 用的封装，插件内部直连 REST | 2026-08-27 | 生效 | - | 讨论确认（R-002 第 7 轮）：老师指出 MCP 是给智能体用的，插件应直连同一服务端口的 RESTful 接口；变更标注（2026-08-29 R-004 定稿）：基础地址由固定单一地址改为多配置动态管理（由激活配置决定，见技术约束-008），直连 REST 原则不变 |
|
||||
| 技术约束-004 | 插件服务端 API 用 webServer 自开路由（如 /odl/api/*），**不直接使用 connection.rpc.intercept('/api')** —— DSH 的 /api 通道只能一个 interceptor（api-gateway 已占用），重复 intercept 会抛错导致插件 apply 失败 | 2026-08-28 | 生效 | - | 迭代 01 复盘沉淀：RPC 冲突导致服务端插件 apply 失败、RPC 404 |
|
||||
| 技术约束-005 | 客户端插件 bundle 必须是 CJS + window.__ModuleLoader__.load({id, factory}) 包装（tsdown 构建 + wrap 脚本），裸 ESM 无法被 DSH 客户端模块系统加载 | 2026-08-28 | 生效 | - | 迭代 01 复盘沉淀：客户端 bundle 未包装导致 loaded without registering via __ModuleLoader__.load |
|
||||
| 技术约束-006 | 客户端 slots.register 的 component 必须是第二参数（register({...}, Component)）；settings schema 必须用 schemastery z.object() 函数式定义 | 2026-08-28 | 生效 | - | 迭代 01 复盘沉淀：component 位置错误致 React #130；普通对象 schema 报 schema is not a function |
|
||||
| 技术约束-007 | 插件安装用 dsh plugin add（自动 reconcile bundles），不直接用 pnpm add；bundle patch 顶层必须是 insert 操作 | 2026-08-28 | 生效 | - | 迭代 01 复盘沉淀：pnpm add 不会更新 dsh.profile.bundles |
|
||||
| 技术约束-008 | QMT 连接配置存储复用 one-divine-lot settings namespace（新增 qmtConnections 字段：list[{id,name,baseUrl,order}] + activeId + defaultId），与策略配置同机制持久化；激活切换 = 更新数据源实例的 baseUrl（数据源按请求读取地址，已核实），立即生效无需重启 DSH；插件启动时激活默认配置（列表为空时回退 cordis 注入的 qmtBaseUrl 兜底，不做自动迁移）；测试连接由服务端代理请求 {baseUrl}/health（避免浏览器跨域） | 2026-08-29 | 生效 | - | R-004 定稿（2026-08-29）：Q1/Q2/Q4/Q5/Q8 确认（启动自动激活默认、立即切换、不迁移、超时不配置化、复用 settings） |
|
||||
| 技术约束-012 | 插件数据存储遵循 **docs/03-设计约束/数据存储设计.md**（JSON data store schema）：份额分配存 store.json（策略为中心）、行情快照存 store.market.json、schema 存 store.schema.json；原子写（临时文件+rename）；旧 allocations.json 启动自动迁移；DataStore 为数据快速展现存在（重启/刷新首屏有数据） | 2026-09-01 | 生效 | - | R-006 及扩展定稿（2026-08-31/09-01）：JSON data store schema 标准化 + 行情持久化 |
|
||||
| 技术约束-011 | 测试/回归脚本**禁止在真实数据上执行写操作**：份额写操作（add/remove/move/clear）必须使用独立数据目录（AllocationStorage 支持 ODL_TEST_DATA_DIR 环境变量或 dataDir 参数指向临时目录），只读端点（positions/summary/strategies/market-snapshot）可直连生产 API | 2026-08-31 | 生效 | - | 2026-08-31 数据误删事故沉淀：回归测试误删大连热电/万顺新材份额分配，老师定「测试用独立数据目录」 |
|
||||
| 技术约束-010 | 行情实时数据由**服务端中转 + 缓存**提供（R-005 演进，2026-08-31 老师改）：DSH 服务端做「WS 订阅 + REST 轮询 + 行情缓存」，前端统一轮询 /odl/api/market-snapshot（不做前端直连，无跨域）；行情持久化到 store.market.json（重启不丢价，首屏快速展现）；QMT Bridge WS 推送是会话级/有状态行为（归属 QMT Bridge 工作空间） | 2026-08-31 | 生效 | - | 变更（2026-08-31）：老师由「前端直连 WS」改为「服务端中转 + 缓存」——解决跨域与 WS 语义不稳定问题；2026-09-01 加行情持久化与启动 prime |
|
||||
| 技术约束-009 | 会话头部快捷切换控件挂载 DSH 开放 slot `conversation.session.header.actions`（多实例挂载点，按 order 排序多插件共存）：客户端插件以独立 id 并排注册（DSH 内置 PTC 标签 order=-10，本控件 order=-9），不改动 DSH 宿主；控件经 ConnectionProvider 包装复用现有 RPC 通道与 /odl/api/* 端点 | 2026-08-29 | 生效 | - | R-004 定稿（2026-08-29）：Q9 确认；宿主代码审查核实 slot 机制与内置插件注册方式 |
|
||||
|
||||
<!-- 示例条目（确认格式后删除）：
|
||||
| 技术约束-001 | 示例：技术栈以 Node.js / TypeScript 为准，不引入未讨论的新框架 | 2026-08-26 | 生效 | - | 讨论确认：优先复用 DSH 既有能力，新框架需论证 |
|
||||
|
||||
@@ -0,0 +1,146 @@
|
||||
# 数据存储设计（JSON Data Store Schema）
|
||||
|
||||
> 策略数据集 + 行情缓存的 JSON data store 设计（R-006 及其扩展，2026-08-31 / 2026-09-01 定）
|
||||
> 本文件是数据存储领域的**设计约束文档**，后续数据存储相关迭代以此为依据。
|
||||
|
||||
## 1. 设计目标
|
||||
|
||||
1. **数据快速展现**：DataStore 的核心目标是「数据快速展现」——份额分配、行情价格持久化，重启/刷新后首屏即有数据，不依赖每次实盘查询。
|
||||
2. **标准化描述**：为每个策略定义标准化的字段描述（schema），在描述之上挂数据集。
|
||||
3. **统一 JSON 操作**：数据量很少（无需数据库/Circe），用 JSON 文件 + 类 JSON Schema 统一读写与校验。
|
||||
|
||||
## 2. 总体架构
|
||||
|
||||
```
|
||||
~/.dsh/one-divine-lot/
|
||||
├── store.schema.json # 数据集 schema（类 JSON Schema，随代码发布，自动生成）
|
||||
├── store.json # 份额分配数据（策略为中心，原子写）
|
||||
└── store.market.json # 行情快照缓存（code → 最新行情，原子写）
|
||||
```
|
||||
|
||||
**分层**：
|
||||
- **策略定义**（id/name/visible/order）：存 DSH settings（~/.dsh/settings.yaml），设置页交互不变
|
||||
- **份额分配**（策略 → 股票 → 股数）：存 store.json（策略为中心）
|
||||
- **行情快照**（code → lastPrice 等）：存 store.market.json（持久化缓存）
|
||||
|
||||
## 3. 数据文件结构与 Schema
|
||||
|
||||
### 3.1 store.schema.json（数据集 schema）
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"kind": "one-divine-lot-data-store",
|
||||
"strategies": {
|
||||
"description": "策略数据集：每个策略一个 dataset（份额分配）",
|
||||
"type": "array",
|
||||
"items": {
|
||||
"strategyId": { "type": "string", "required": true, "description": "策略 id（与 settings 中的策略一致）" },
|
||||
"dataset": {
|
||||
"type": "array",
|
||||
"description": "该策略的持仓数据集（份额分配）",
|
||||
"items": {
|
||||
"code": { "type": "string", "required": true, "description": "证券代码（含后缀，如 600719.SH）" },
|
||||
"shares": { "type": "number", "required": true, "description": "份额（股数，>0）" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 store.json（份额分配，策略为中心）
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"strategies": [
|
||||
{
|
||||
"strategyId": "grid-supermarket",
|
||||
"dataset": [
|
||||
{ "code": "600719.SH", "shares": 800 },
|
||||
{ "code": "300057.SZ", "shares": 1000 }
|
||||
]
|
||||
},
|
||||
{
|
||||
"strategyId": "manual-t",
|
||||
"dataset": [
|
||||
{ "code": "600719.SH", "shares": 1000 }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**数据视角**：按策略查持仓（策略为中心），比旧 code 为中心（allocations.json）更贴合业务。
|
||||
|
||||
### 3.3 store.market.json（行情快照缓存）
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"savedAt": 1788193491108,
|
||||
"quotes": {
|
||||
"600719.SH": {
|
||||
"time": 1788159604000,
|
||||
"timetag": "20260831 15:00:04",
|
||||
"lastPrice": 7.16,
|
||||
"open": 7.19,
|
||||
"high": 7.24,
|
||||
"low": 7.02,
|
||||
"lastClose": 7.22,
|
||||
"volume": 63523,
|
||||
"amount": 45341300
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**用途**：宿主重启后首屏快速展示上次价格（不依赖实盘订阅）；实盘推送/轮询做增量更新并定期写回。
|
||||
|
||||
## 4. 数据流
|
||||
|
||||
```
|
||||
启动时：
|
||||
DataStore.load() → 读 store.json（份额分配）
|
||||
DataStore.loadMarket() → 读 store.market.json（行情缓存，首屏有价）
|
||||
MarketFeed._primePositions() → 主动拉持仓盘口 → 写缓存（服务端启动即预热最新价）
|
||||
|
||||
实盘中：
|
||||
MarketFeed WS 推送 / REST 定时刷新 → MarketDataHub.ingest() → 内存缓存
|
||||
MarketDataHub 防抖 3s → DataStore.setMarketQuotes() → store.market.json
|
||||
|
||||
查询时（market-snapshot）：
|
||||
MarketDataHub.getByCodes() → 内存 → 磁盘 → REST 补拉（三级命中）
|
||||
```
|
||||
|
||||
## 5. 关键设计决策
|
||||
|
||||
| 决策 | 结论 | 理由 |
|
||||
|---|---|---|
|
||||
| 存储介质 | JSON 文件（不引入数据库） | 数据量很少，JSON + schema 足够 |
|
||||
| 策略定义位置 | DSH settings（不迁 store） | 设置页交互不变，查询简单 |
|
||||
| 份额分配结构 | 策略为中心（strategies[].dataset） | 贴合业务视角，schema 统一描述 |
|
||||
| dataset 格式 | [{code, shares}] 数组 | 可扩展字段（未来加成本价/备注） |
|
||||
| 行情缓存 | 持久化（store.market.json） | DataStore 为数据快速展现存在，重启不丢价 |
|
||||
| 写入 | 原子写（临时文件 + rename） | 防损坏，多次写安全 |
|
||||
| 测试隔离 | ODL_TEST_DATA_DIR 环境变量或 dataDir 参数 | 防误删真实数据（技术约束-011） |
|
||||
|
||||
## 6. 迁移
|
||||
|
||||
- 旧 allocations.json（code 为中心）→ 新 store.json（策略为中心）：**启动时自动迁移**，旧文件备份为 allocations.json.bak
|
||||
- 迁移逻辑在 DataStore._migrateFromLegacy()：code 为中心 → 策略为中心聚合
|
||||
|
||||
## 7. 对应实现
|
||||
|
||||
| 模块 | 职责 | 文件 |
|
||||
|---|---|---|
|
||||
| DataStore | 份额分配 + 行情持久化读写、迁移、schema | src/component/DataStore.js |
|
||||
| PositionManager | 份额业务逻辑（依赖 DataStore） | src/component/PositionManager.js |
|
||||
| MarketDataHub | 行情缓存（内存 + 磁盘持久化 + 查询） | src/component/MarketDataHub.js |
|
||||
| MarketFeed | 行情获取（WS + REST 定时刷新 + 启动 prime） | src/component/MarketFeed.js |
|
||||
|
||||
## 8. 约束条目（引用）
|
||||
|
||||
- 技术约束-011：测试/回归脚本禁止在真实数据上执行写操作（独立数据目录）
|
||||
- 本文件为新领域设计约束，后续数据存储变更以本文件为最终依据
|
||||
Reference in New Issue
Block a user