feat: 添加设计文件packages

2026-02-11 16:01:42 +08:00
parent 161781cbbd
commit 571465cfbb
26 changed files with 15808 additions and 5 deletions
--- a/packages/design-document/机生文档/设计优化评估-简化交易记录.md
+++ b/packages/design-document/机生文档/设计优化评估-简化交易记录.md
@@ -0,0 +1,419 @@
+# 设计优化评估：简化交易记录方案
+
+## 一、优化方案概述
+
+### 1.1 核心设计思路
+
+**原设计（记录每次交易）：**
+- 用户每次买入/卖出都需要记录：价格、份额、费用、日期
+- 系统自动计算加权平均成本价
+- 保留完整的交易历史记录
+
+**新设计（直接修改持仓）：**
+- 被动变更（分红、拆股、送股）：系统自动完成 ✅
+- 主动变更（买入、卖出、追加买入）：用户直接修改成本价和份数
+- 不记录每次交易的详细历史
+
+### 1.2 用户场景分析
+
+**目标用户：多券商用户**
+- 在多个券商都有账户
+- 需要汇总查看整体持仓和收益
+- 不需要替代券商系统，只是汇总统计
+
+**核心需求：**
+- 简单快速更新持仓
+- 自动计算收益和收益率
+- 未来支持计划和复盘功能
+
+---
+
+## 二、方案评估
+
+### 2.1 ✅ 优势分析
+
+#### 1. **操作简单直接**
+```
+原设计：买入 → 输入价格、份额、费用 → 系统计算成本价
+新设计：直接修改成本价和份数 → 完成
+```
+- ✅ 操作步骤减少 50% 以上
+- ✅ 学习成本低，上手快
+- ✅ 适合快速更新多券商汇总数据
+
+#### 2. **符合多券商场景**
+- ✅ 用户已经在券商系统完成交易，这里只是汇总
+- ✅ 不需要重复录入交易细节
+- ✅ 可以定期（如每周/每月）批量更新持仓
+
+#### 3. **降低维护成本**
+- ✅ 不需要记录每次交易的费用、时间等细节
+- ✅ 减少数据录入错误
+- ✅ 减少系统复杂度
+
+#### 4. **灵活性更高**
+- ✅ 用户可以手动调整成本价（如考虑交易费用后的实际成本）
+- ✅ 可以快速修正错误
+- ✅ 支持"模糊"记录（不需要精确到每笔交易）
+
+### 2.2 ⚠️ 潜在问题分析
+
+#### 1. **收益率计算准确性**
+
+**问题：**
+- 基金净值法需要知道每次资金流入流出的时间点
+- 资金加权法（IRR）需要完整的现金流记录
+- 如果只有持仓快照，无法准确计算时间加权收益率
+
+**影响评估：**
+- ⚠️ **时间加权收益率**：需要每日资产快照，如果只有持仓数据，可以计算，但精度可能受影响
+- ⚠️ **资金加权收益率（IRR）**：需要现金流记录，如果只记录持仓，无法计算
+- ✅ **累计收益率**：可以计算（当前资产 - 累计投入）
+- ✅ **年化收益率**：可以计算（基于累计收益率）
+
+**解决方案：**
+- 保留"资金变动记录"（不是交易记录，而是资金流入流出）
+- 记录：日期、金额、类型（投入/提取）
+- 这样可以计算 IRR，同时保持操作简单
+
+#### 2. **计划和复盘功能的影响**
+
+**问题：**
+- PRD 中提到需要记录"交易思考"和"复盘"
+- 如果只有持仓快照，如何关联思考和复盘？
+
+**影响评估：**
+- ⚠️ 无法关联到具体的某笔交易
+- ✅ 可以关联到持仓（某只股票的整体思考）
+- ✅ 可以记录时间点的思考（如"2024年1月加仓茅台"）
+
+**解决方案：**
+- 持仓级别的思考记录（不是交易级别）
+- 时间线记录（记录某个时间点的持仓变化和思考）
+- 支持"持仓变更记录"（记录成本价和份数的变化，但不记录交易细节）
+
+#### 3. **数据可追溯性**
+
+**问题：**
+- 如果只记录当前持仓，无法追溯历史
+- 无法回答"什么时候买入的？"、"买入价格是多少？"
+
+**影响评估：**
+- ⚠️ 失去详细的交易历史
+- ✅ 可以保留持仓变更历史（成本价和份数的变化）
+- ✅ 对于多券商汇总场景，这个需求可能不是核心
+
+**解决方案：**
+- 保留"持仓变更记录"（简化版）
+  - 日期
+  - 变更类型（手动调整/买入/卖出）
+  - 变更前：成本价、份数
+  - 变更后：成本价、份数
+  - 可选：思考/备注
+
+#### 4. **成本价计算的准确性**
+
+**问题：**
+- 用户手动输入成本价，可能不准确
+- 多笔买入的加权平均成本价需要用户自己计算
+
+**影响评估：**
+- ⚠️ 用户需要自己计算加权平均成本价
+- ⚠️ 可能输入错误
+- ✅ 但用户可以根据券商系统的成本价直接输入
+
+**解决方案：**
+- 提供"成本价计算器"工具
+- 支持批量导入（从券商系统导出后导入）
+- 提供成本价验证提示
+
+---
+
+## 三、优化后的设计方案
+
+### 3.1 数据模型调整
+
+#### 持仓表（Position）- 保持不变
+```typescript
+interface Position {
+  id: string;
+  accountId: string;
+  symbol: string;
+  name: string;
+  shares: number;           // 持仓份额
+  costPrice: number;        // 成本价（用户直接修改）
+  currentPrice: number;     // 当前价格（系统自动更新）
+  market: string;
+  currency: string;
+  status: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+```
+
+#### 持仓变更记录表（PositionChange）- 新增
+```typescript
+interface PositionChange {
+  id: string;
+  positionId: string;
+  changeDate: Date;         // 变更日期
+  changeType: 'manual' | 'buy' | 'sell' | 'auto'; // 变更类型
+  beforeShares: number;     // 变更前份数
+  beforeCostPrice: number;  // 变更前成本价
+  afterShares: number;     // 变更后份数
+  afterCostPrice: number;   // 变更后成本价
+  notes?: string;           // 备注/思考
+  createdAt: Date;
+}
+```
+
+#### 资金变动记录表（CashFlow）- 新增（用于计算 IRR）
+```typescript
+interface CashFlow {
+  id: string;
+  accountId: string;
+  flowDate: Date;           // 资金变动日期
+  flowType: 'deposit' | 'withdraw' | 'dividend' | 'interest'; // 类型
+  amount: number;           // 金额（正数表示投入，负数表示提取）
+  currency: string;
+  notes?: string;           // 备注
+  createdAt: Date;
+}
+```
+
+#### 持仓思考表（PositionThought）- 新增（用于计划和复盘）
+```typescript
+interface PositionThought {
+  id: string;
+  positionId: string;
+  thoughtDate: Date;        // 思考日期
+  thoughtType: 'plan' | 'review' | 'note'; // 类型
+  content: string;          // 思考内容
+  createdAt: Date;
+  updatedAt: Date;
+}
+```
+
+### 3.2 操作流程设计
+
+#### 买入/卖出操作（简化版）
+
+```
+用户操作：
+1. 打开持仓列表
+2. 点击"编辑"或"调整"
+3. 直接修改：
+   - 成本价（如：从 100 改为 95，表示加仓后新的加权成本价）
+   - 份数（如：从 100 股改为 150 股）
+4. 可选：添加备注/思考
+5. 保存
+
+系统处理：
+1. 记录变更前状态
+2. 更新持仓（成本价、份数）
+3. 记录持仓变更记录
+4. 更新总资产和收益率
+```
+
+#### 被动变更（系统自动）
+
+```
+分红/拆股/送股：
+1. 系统检测或用户触发
+2. 自动计算新的成本价和份数
+3. 更新持仓
+4. 记录持仓变更记录（changeType = 'auto'）
+```
+
+### 3.3 收益率计算调整
+
+#### 时间加权收益率（基金净值法）
+
+**方案：基于每日资产快照**
+```javascript
+// 需要每日记录资产快照
+interface DailySnapshot {
+  date: Date;
+  totalAsset: number;      // 总资产
+  totalCost: number;       // 总成本（累计投入）
+  netValue: number;        // 单位净值
+}
+
+// 计算方式
+function calculateTimeWeightedReturn(snapshots) {
+  let cumulativeReturn = 1;
+  for (let i = 1; i < snapshots.length; i++) {
+    const periodReturn = (snapshots[i].netValue - snapshots[i-1].netValue) / snapshots[i-1].netValue;
+    cumulativeReturn *= (1 + periodReturn);
+  }
+  return cumulativeReturn - 1;
+}
+```
+
+**关键点：**
+- ✅ 需要每日资产快照（系统自动生成）
+- ✅ 不依赖交易记录，只依赖资产快照
+- ✅ 可以准确计算
+
+#### 资金加权收益率（IRR）
+
+**方案：基于资金变动记录**
+```javascript
+// 使用 CashFlow 记录
+function calculateIRR(cashFlows) {
+  // cashFlows: 资金流入流出记录
+  // 正数：投入资金
+  // 负数：提取资金
+  // 最后一条：当前资产价值（负数，表示"提取"）
+  
+  // 使用二分法或牛顿法求解 IRR
+}
+```
+
+**关键点：**
+- ✅ 需要记录资金变动（不是交易记录）
+- ✅ 用户只需要记录：什么时候投入多少钱、什么时候提取多少钱
+- ✅ 比记录每笔交易简单很多
+
+---
+
+## 四、方案对比总结
+
+### 4.1 功能对比
+
+| 功能 | 原设计（记录交易） | 新设计（直接修改） | 评估 |
+|------|------------------|-------------------|------|
+| 操作复杂度 | 高（每次交易需录入） | 低（直接修改） | ✅ 新设计更简单 |
+| 数据准确性 | 高（系统计算） | 中（用户输入） | ⚠️ 需要验证 |
+| 交易历史 | 完整 | 简化（变更记录） | ⚠️ 失去细节 |
+| 收益率计算 | 精确 | 可接受 | ✅ 通过快照和资金流可计算 |
+| 计划和复盘 | 可关联交易 | 可关联持仓 | ✅ 两种都支持 |
+| 多券商场景 | 适合 | 更适合 | ✅ 新设计更适合 |
+
+### 4.2 适用场景分析
+
+**新设计更适合：**
+- ✅ 多券商用户汇总统计
+- ✅ 不需要详细交易历史的用户
+- ✅ 希望快速更新持仓的用户
+- ✅ 主要关注收益统计，不关注交易细节
+
+**原设计更适合：**
+- ✅ 需要完整交易历史的用户
+- ✅ 需要精确计算每笔交易收益的用户
+- ✅ 单券商用户（可以对接券商API）
+
+### 4.3 推荐方案
+
+**推荐采用新设计（直接修改持仓），但需要补充：**
+
+1. ✅ **保留持仓变更记录**（简化版，不记录交易细节）
+2. ✅ **保留资金变动记录**（用于计算 IRR）
+3. ✅ **每日资产快照**（用于计算时间加权收益率）
+4. ✅ **持仓思考记录**（用于计划和复盘）
+
+**这样既简化了操作，又保证了核心功能的实现。**
+
+---
+
+## 五、最终建议
+
+### 5.1 核心设计原则
+
+1. **被动变更 = 系统自动**
+   - 分红、拆股、送股等由系统自动处理
+   - 用户只需确认或触发
+
+2. **主动变更 = 直接修改持仓**
+   - 买入/卖出：直接修改成本价和份数
+   - 可选：记录变更备注/思考
+   - 系统记录变更历史（简化版）
+
+3. **资金变动 = 单独记录**
+   - 记录资金投入/提取（不是交易）
+   - 用于计算 IRR
+   - 操作简单（只需记录日期和金额）
+
+4. **思考记录 = 关联持仓**
+   - 不是关联交易，而是关联持仓
+   - 支持时间线展示
+   - 支持计划和复盘
+
+### 5.2 数据模型建议
+
+**核心表：**
+- `positions` - 持仓表（用户直接修改）
+- `position_changes` - 持仓变更记录（系统自动记录）
+- `cash_flows` - 资金变动记录（用户记录投入/提取）
+- `daily_snapshots` - 每日资产快照（系统自动生成）
+- `position_thoughts` - 持仓思考记录（用户记录思考）
+
+**移除或简化：**
+- ~~`transactions`~~ - 不再需要详细的交易记录表
+- 或者保留但改为可选（高级用户可以使用）
+
+### 5.3 用户体验优化
+
+1. **提供成本价计算器**
+   - 用户输入多笔买入价格和份额
+   - 系统计算加权平均成本价
+   - 用户可以直接复制使用
+
+2. **支持批量导入**
+   - 从券商系统导出持仓
+   - 批量导入到系统
+   - 减少手动输入
+
+3. **变更历史展示**
+   - 展示持仓变更时间线
+   - 显示每次变更的成本价和份数变化
+   - 支持添加思考/备注
+
+4. **智能提示**
+   - 成本价变化异常时提示
+   - 份数变化异常时提示
+   - 帮助用户发现输入错误
+
+---
+
+## 六、结论
+
+### 6.1 方案评估结果
+
+**✅ 新设计（直接修改持仓）更适合您的场景**
+
+**理由：**
+1. ✅ 操作简单，符合多券商汇总场景
+2. ✅ 核心功能（收益计算）可以通过资产快照和资金流实现
+3. ✅ 计划和复盘功能可以通过持仓思考记录实现
+4. ✅ 用户体验更好，上手更快
+
+**需要注意：**
+1. ⚠️ 需要补充资金变动记录（用于 IRR 计算）
+2. ⚠️ 需要每日资产快照（用于时间加权收益率）
+3. ⚠️ 需要持仓变更记录（用于追溯和思考关联）
+
+### 6.2 实施建议
+
+**第一阶段：核心功能**
+- 持仓直接编辑（成本价、份数）
+- 持仓变更记录
+- 每日资产快照
+- 基础收益计算
+
+**第二阶段：完善功能**
+- 资金变动记录
+- 时间加权收益率和 IRR 计算
+- 持仓思考记录
+
+**第三阶段：高级功能**
+- 计划和复盘
+- 批量导入
+- 成本价计算器
+
+---
+
+**文档版本**：v1.0  
+**创建日期**：2024年  
+**评估结论**：✅ 推荐采用新设计，但需要补充资金流和快照功能
+