Epics and Stories: asset-light MVP

版本: 1.0.0
日期: 2025-12-20
关联 PRD: PRD

概览

本文档将 PRD 中的功能需求拆分为可执行的 Epics 和 Stories，用于指导开发迭代。

Epic 总览

优先级定义

• P0: MVP 必须完成，阻塞发布
• P1: MVP 应该完成，可降级
• P2: MVP 可选，后续迭代

E0: 项目基础设施

目标: 搭建项目骨架，建立开发基础

E0-S1: 项目初始化

优先级: P0

描述:
作为开发者，我需要初始化 Dioxus 桌面项目，配置基础开发环境，以便开始功能开发。

验收标准:

• 创建 Cargo 项目，配置 Dioxus Desktop 依赖
• 配置 macOS 应用 bundle 设置（应用名称、图标占位）
• 应用能够成功编译并启动空白窗口
• 建立基础目录结构（src/components, src/models, src/services）
• 配置 rustfmt 和 clippy

技术备注:

依赖: dioxus = { version = "0.5", features = ["desktop"] }

E0-S2: 数据持久化层

优先级: P0

描述:
作为开发者，我需要建立本地数据存储机制，以便应用能够保存和读取用户数据。

验收标准:

• 选定并集成 SQLite 作为本地数据库
• 实现数据库初始化和迁移机制
• 创建基础的 CRUD 操作 trait
• 数据文件存储在用户目录下的应用专属位置
• 错误处理：数据库损坏时给出友好提示

技术备注:

建议使用 rusqlite 或 sqlx (with sqlite feature)
数据路径: ~/Library/Application Support/asset-light/

E0-S3: 应用布局框架

优先级: P0

描述:
作为用户，我希望应用有清晰的导航结构，以便快速切换不同功能模块。

验收标准:

• 实现侧边栏导航组件
• 导航项包含：首页、资产管理、盘点历史、配置方案、收益分析
• 当前激活项有视觉高亮
• 路由系统支持页面切换
• 页面切换响应时间 < 200ms

界面参考:

┌─────────┬────────────────────────────────┐
│ 侧边栏   │                                │
│ ──────  │         主内容区域              │
│ 首页    │                                │
│ 资产    │                                │
│ 历史    │                                │
│ 配置    │                                │
│ 收益    │                                │
└─────────┴────────────────────────────────┘

E0-S4: 全局状态管理

优先级: P0

描述:
作为开发者，我需要建立全局状态管理机制，以便跨组件共享数据（如当前资产列表、激活配置方案）。

验收标准:

• 使用 Dioxus Signal 或 Context 实现全局状态
• 定义核心状态结构：AppState（资产列表、快照列表、配置方案列表、当前激活方案）
• 状态变更能触发相关组件重渲染
• 状态持久化：应用启动时从数据库加载，变更时自动保存

E1: 资产盘点模块

目标: 实现资产条目的增删改查和快照式盘点功能

E1-S1: 资产条目数据模型

优先级: P0
PRD 引用: FR-F1-01, FR-F1-02

描述:
作为开发者，我需要定义资产条目的数据模型和数据库表结构。

验收标准:

• 定义 Asset 结构体，包含：id, name, category, sub_category, current_value, notes, created_at, updated_at
• 定义 Category 枚举：Cash, Stable, Advanced
• 创建 assets 表并实现 CRUD 操作
• 支持按类别查询资产列表
• 金额精度：小数点后 2 位

数据模型:

#![allow(unused)]
fn main() {
pub enum Category {
    Cash,      // 现金类
    Stable,    // 稳健类
    Advanced,  // 进阶类
}

pub struct Asset {
    pub id: Uuid,
    pub name: String,
    pub category: Category,
    pub sub_category: Option<String>,
    pub current_value: Decimal,
    pub notes: Option<String>,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}
}

E1-S2: 新增资产条目

优先级: P0
PRD 引用: US-F1-01

描述:
作为用户，我希望能够新增一个资产条目（包含名称、类别、当前市值），以便记录我持有的资产。

验收标准:

• 提供"新增资产"按钮，点击弹出模态框/侧边栏表单
• 表单字段：名称（必填）、类别（必填，下拉选择）、子类别（可选）、市值（必填，数字输入）、备注（可选）
• 名称验证：非空，最大 100 字符
• 市值验证：非负数，自动格式化为 2 位小数
• 保存成功后关闭表单，资产列表自动刷新
• 保存失败时显示错误提示

E1-S3: 编辑资产条目

优先级: P0
PRD 引用: US-F1-02

描述:
作为用户，我希望能够编辑已有资产条目的信息，以便修正录入错误或更新资产状态。

验收标准:

• 资产列表中每个条目有"编辑"操作入口
• 点击编辑打开预填充的表单
• 表单验证规则与新增一致
• 保存时自动更新 updated_at 时间戳
• 支持取消编辑，不保存变更

E1-S4: 删除资产条目

优先级: P0
PRD 引用: US-F1-03, BR-F1-03

描述:
作为用户，我希望能够删除不再持有的资产条目，以便保持资产列表的准确性。

验收标准:

• 资产列表中每个条目有"删除"操作入口
• 点击删除弹出确认对话框："确定删除资产「XXX」吗？此操作不可撤销。"
• 确认后从数据库删除记录
• 历史快照中的该资产数据保留（快照不可变原则）
• 删除后列表自动刷新

E1-S5: 资产列表展示

优先级: P0
PRD 引用: US-F1-04, UI-F1-01

描述:
作为用户，我希望资产条目能够按类别（现金类/稳健类/进阶类）组织展示，以便快速定位和管理。

验收标准:

• 资产列表按三个类别分组展示
• 每个类别区块显示：类别名称、资产数量、类别总市值
• 每个资产条目显示：名称、子类别（如有）、当前市值
• 类别区块支持折叠/展开
• 空类别显示"暂无资产"占位
• 页面顶部显示资产总数和总市值

界面参考:

资产管理                          总计: 10 项 ¥ 500,000.00
──────────────────────────────────────────────────────────
▼ 现金类 (3 项)                              ¥ 100,000.00
  ├─ 余额宝                                   ¥ 50,000.00
  ├─ 活期存款          [银行活期]             ¥ 30,000.00
  └─ 定期存单          [大额存单]             ¥ 20,000.00

▼ 稳健类 (2 项)                              ¥ 150,000.00
  ├─ XX债券基金        [纯债]                 ¥ 80,000.00
  └─ YY理财产品        [银行理财]             ¥ 70,000.00

▼ 进阶类 (5 项)                              ¥ 250,000.00
  ├─ 沪深300ETF        [宽基指数]            ¥ 100,000.00
  └─ ...

E1-S6: 执行盘点操作

优先级: P0
PRD 引用: US-F1-05, UI-F1-03, FR-F1-03, FR-F1-04

描述:
作为用户，我希望能够执行一次"盘点"操作，批量更新所有资产的当前市值，并自动记录盘点时间戳。

验收标准:

• 资产管理页有"开始盘点"按钮
• 点击后进入盘点模式，页面有明显的视觉区分（如顶部提示条）
• 盘点模式下，每个资产的市值变为可编辑输入框
• 每个输入框旁显示"上次市值"作为参考
• 提供"完成盘点"按钮：
  • 创建盘点快照，记录当前所有资产的状态
  • 更新各资产的 current_value
  • 退出盘点模式，显示成功提示
• 提供"取消盘点"按钮：放弃所有修改，退出盘点模式
• 业务规则：至少有 1 个资产才能盘点
• 业务规则：每天最多 5 次盘点（超出提示并阻止）

盘点快照数据:

#![allow(unused)]
fn main() {
pub struct Snapshot {
    pub id: Uuid,
    pub snapshot_date: NaiveDate,
    pub created_at: DateTime<Utc>,
    pub total_value: Decimal,
    pub items: Vec<SnapshotItem>,
}

pub struct SnapshotItem {
    pub asset_id: Uuid,
    pub asset_name: String,
    pub category: Category,
    pub sub_category: Option<String>,
    pub value: Decimal,
}
}

E1-S7: 查看盘点历史列表

优先级: P0
PRD 引用: US-F1-06, UI-F1-04

描述:
作为用户，我希望能够查看历史盘点记录列表，以便回顾资产变化轨迹。

验收标准:

• 盘点历史页以时间线形式展示所有历史快照
• 每条记录显示：盘点日期、资产总额
• 每条记录显示与上次盘点的变化：金额差（+¥1,234 或 -¥567）、百分比（+2.5%）
• 记录按时间倒序排列（最新在上）
• 空状态显示"暂无盘点记录，请先进行一次盘点"
• 支持点击记录查看详情（见 E1-S8）

E1-S8: 查看盘点快照详情

优先级: P1
PRD 引用: US-F1-07

描述:
作为用户，我希望能够查看某次历史盘点的详细快照，以便了解当时的资产状态。

验收标准:

• 点击历史记录可展开/跳转至详情视图
• 详情视图显示：盘点日期、总市值、各类别市值
• 显示该快照中所有资产条目：名称、类别、子类别、当时市值
• 提供返回按钮回到历史列表

E2: 配置方案模块

目标: 实现目标配置方案的创建、编辑和管理

E2-S1: 配置方案数据模型

优先级: P0
PRD 引用: FR-F2-01, FR-F2-02

描述:
作为开发者，我需要定义配置方案的数据模型和数据库表结构。

验收标准:

• 定义 AllocationPlan 结构体
• 定义 Allocation 结构体（配置项）
• 创建数据库表并实现 CRUD 操作
• 支持查询当前激活方案
• 应用首次启动时自动创建默认"平衡型"方案并激活

数据模型:

#![allow(unused)]
fn main() {
pub struct AllocationPlan {
    pub id: Uuid,
    pub name: String,
    pub description: Option<String>,
    pub is_active: bool,
    pub allocations: Vec<Allocation>,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}

pub struct Allocation {
    pub category: Category,
    pub target_percentage: Decimal,  // 0-100
    pub min_percentage: Option<Decimal>,
    pub max_percentage: Option<Decimal>,
}
}

E2-S2: 创建配置方案

优先级: P0
PRD 引用: US-F2-01, UI-F2-02

描述:
作为用户，我希望能够创建一个配置方案，定义各资产类别的目标占比，以便作为资产配置的参照标准。

验收标准:

• 提供"新建方案"按钮，打开方案编辑器
• 编辑器包含：方案名称（必填）、描述（可选）
• 提供三个类别的占比设置（滑块或数字输入）
• 实时显示占比总和，必须 = 100%
• 总和不等于 100% 时禁用保存按钮并提示
• 可选：饼图预览目标配置
• 保存后方案出现在方案列表中

E2-S3: 编辑配置方案

优先级: P0
PRD 引用: US-F2-02

描述:
作为用户，我希望能够编辑已有的配置方案，以便根据投资策略变化调整目标配置。

验收标准:

• 方案列表中每个方案有"编辑"操作入口
• 点击编辑打开预填充的方案编辑器
• 编辑规则与创建一致
• 保存时更新 updated_at 时间戳

E2-S4: 删除配置方案

优先级: P1
PRD 引用: US-F2-03, BR-F2-04, BR-F2-05

描述:
作为用户，我希望能够删除不再使用的配置方案，以便保持方案列表简洁。

验收标准:

• 方案列表中每个方案有"删除"操作入口
• 当前激活方案不可删除，删除按钮置灰并提示"请先切换激活方案"
• 系统仅剩 1 个方案时不可删除，提示"至少保留一个方案"
• 点击删除弹出确认对话框
• 确认后删除方案

E2-S5: 激活配置方案

优先级: P0
PRD 引用: US-F2-04, BR-F2-03

描述:
作为用户，我希望能够将某个方案设为"当前激活"，用于计算配置偏离度。

验收标准:

• 方案列表中每个非激活方案有"设为当前"操作入口
• 当前激活方案有明显视觉标识（如徽章、高亮背景）
• 点击"设为当前"后：
  • 该方案变为激活状态
  • 原激活方案变为非激活
  • 资产视图页的偏离度重新计算
• 系统始终有且仅有一个激活方案

E2-S6: 预设方案模板

优先级: P1
PRD 引用: US-F2-06, UI-F2-03

描述:
作为用户，我希望系统提供预设的配置方案模板作为起点，以便快速开始使用。

验收标准:

• 新建方案时提供"从模板创建"选项
• 提供 3 套预设模板：
  • 保守型：Cash 30%, Stable 50%, Advanced 20%
  • 平衡型：Cash 20%, Stable 40%, Advanced 40%
  • 进取型：Cash 10%, Stable 20%, Advanced 70%
• 选择模板后自动填充占比，用户可进一步调整
• 应用首次启动自动创建"平衡型"方案

E3: 资产视图模块

目标: 展示资产全貌，可视化配置对比和偏离情况

E3-S1: 资产总览卡片

优先级: P0
PRD 引用: US-F3-01, UI-F3-01

描述:
作为用户，我希望在首页看到资产总额和各类别的分布情况，以便快速了解资产全貌。

验收标准:

• 首页顶部显示资产总额卡片，突出显示总市值
• 显示上次盘点日期
• 显示各类别的市值和占比
• 无资产时显示引导文案"暂无资产，点击添加您的第一个资产"

E3-S2: 配置对比图表

优先级: P0
PRD 引用: US-F3-02, UI-F3-03

描述:
作为用户，我希望能够直观对比当前配置与目标配置的差异，以便判断是否需要调整。

验收标准:

• 首页展示双饼图：左侧"当前配置"，右侧"目标配置"
• 同类别使用相同颜色
• 鼠标悬停显示具体金额和百分比
• 目标配置来自当前激活方案
• 无激活方案时提示"请先创建配置方案"

E3-S3: 偏离状态列表

优先级: P0
PRD 引用: US-F3-03, US-F3-04, FR-F3-01, FR-F3-02, UI-F3-02

描述:
作为用户，我希望当某类别偏离目标超过阈值时，系统能够高亮提示，并看到各类别的偏离百分比。

验收标准:

• 首页显示类别配置对比表格
• 表格列：类别、当前占比、目标占比、偏离度、状态
• 偏离度计算：当前占比 - 目标占比
• 状态判定（默认容忍度 5%）：
  • |偏离度| ≤ 5%：正常（绿色 ✓）
  • |偏离度| > 5%：轻度偏离（黄色 ⚠️）
  • |偏离度| > 10%：严重偏离（红色 ❗）
• 偏离度显示正负符号：+5%（超配）、-3%（低配）

偏离计算逻辑:

#![allow(unused)]
fn main() {
fn calculate_deviation(current: Decimal, target: Decimal) -> DeviationResult {
    let deviation = current - target;
    let abs_deviation = deviation.abs();
    
    let status = if abs_deviation <= Decimal::new(5, 0) {
        DeviationStatus::Normal
    } else if abs_deviation <= Decimal::new(10, 0) {
        DeviationStatus::Mild
    } else {
        DeviationStatus::Severe
    };
    
    let direction = if deviation > Decimal::ZERO {
        DeviationDirection::Overweight
    } else {
        DeviationDirection::Underweight
    };
    
    DeviationResult { deviation, status, direction }
}
}

E3-S4: 无数据状态处理

优先级: P1

描述:
作为用户，当我没有资产或没有配置方案时，我希望看到友好的引导提示。

验收标准:

• 无资产时：显示空状态插图 + "开始添加资产"按钮
• 无配置方案时：显示"创建配置方案"按钮
• 无盘点记录时：偏离度显示"--"，提示"请先完成一次盘点"

E3-S5: 再平衡方向提示

优先级: P2
PRD 引用: US-F3-05

描述:
作为用户，我希望能够一键查看再平衡所需的资金调整方向，以便规划调仓。

验收标准:

• 偏离状态列表增加"调整方向"列
• 超配类别显示"↓ 减少"
• 低配类别显示"↑ 增加"
• 正常类别显示"- 维持"
• 可选：显示建议调整金额（粗略估算）

E4: 收益分析模块

目标: 基于盘点快照计算和展示收益情况

E4-S1: 周期收益计算

优先级: P0
PRD 引用: US-F4-01, US-F4-02, FR-F4-01, FR-F4-02

描述:
作为用户，我希望看到选定时间段内的资产总收益（金额和百分比），并能按季度/年度查看。

验收标准:

• 收益分析页顶部提供周期选择器
• 支持选择：季度（Q1-Q4）、年度
• 支持选择年份
• 显示本期收益金额（绝对值）
• 显示本期收益率（百分比）
• 显示期初/期末总市值
• 至少需要 2 个快照才能计算，否则显示"数据不足"

收益计算:

#![allow(unused)]
fn main() {
fn calculate_period_return(start_snapshot: &Snapshot, end_snapshot: &Snapshot) -> ReturnResult {
    let absolute_return = end_snapshot.total_value - start_snapshot.total_value;
    
    let return_rate = if start_snapshot.total_value > Decimal::ZERO {
        (absolute_return / start_snapshot.total_value) * Decimal::new(100, 0)
    } else {
        Decimal::ZERO  // 或返回 N/A
    };
    
    ReturnResult {
        period: (start_snapshot.snapshot_date, end_snapshot.snapshot_date),
        start_value: start_snapshot.total_value,
        end_value: end_snapshot.total_value,
        absolute_return,
        return_rate,
    }
}
}

E4-S2: 收益归因分析

优先级: P0
PRD 引用: US-F4-03, FR-F4-04, UI-F4-01, UI-F4-02

描述:
作为用户，我希望看到各资产类别的收益贡献，以便了解哪些类别在产生收益。

验收标准:

• 收益分析页显示收益归因表格
• 表格列：类别、期初市值、期末市值、收益金额、收益率、贡献度
• 贡献度 = 该类别收益 / 总收益 × 100%
• 正收益显示绿色，负收益显示红色
• 可选：横向条形图可视化各类别收益贡献

E4-S3: 资产趋势图

优先级: P1
PRD 引用: US-F4-04, UI-F4-03

描述:
作为用户，我希望看到资产总额的历史变化趋势图，以便直观感受资产增长轨迹。

验收标准:

• 收益分析页底部显示折线图
• X 轴：盘点日期
• Y 轴：资产总额
• 数据点来自历史盘点快照
• 鼠标悬停显示具体日期和金额
• 至少 2 个数据点才显示趋势线
• 可选：支持时间范围筛选

E4-S4: 自定义周期对比

优先级: P2
PRD 引用: US-F4-05

描述:
作为用户，我希望能够选择任意两个盘点时间点进行收益对比，以便灵活分析。

验收标准:

• 提供"自定义对比"入口
• 可选择起始快照和结束快照
• 计算并显示两个时间点之间的收益
• 复用周期收益的展示组件

E4-S5: 无数据状态处理

优先级: P1

描述:
作为用户，当盘点数据不足时，我希望看到友好的提示。

验收标准:

• 无快照时：显示"暂无盘点数据，请先进行资产盘点"
• 仅 1 个快照时：显示"需要至少 2 次盘点才能计算收益"
• 选定周期内无快照时：显示"该周期内暂无盘点记录"

开发建议顺序

迭代 1：基础骨架（预计 3-5 天）

迭代 2：资产管理核心（预计 5-7 天）

迭代 3：盘点功能（预计 3-5 天）

迭代 4：配置方案（预计 3-5 天）

迭代 5：资产视图（预计 3-5 天）

迭代 6：收益分析（预计 3-5 天）

迭代 7：完善优化（预计 2-3 天）

修订历史

This document breaks down the PRD into implementable Epics and Stories.

Next: Architecture design will define the technical implementation approach.