# FinancialReport MVP 项目需求文档

## 项目概述

### 核心目标
构建一个独立的Docker容器项目，用于生成综合性的FinancialReport.pdf报告。MVP版本专注于本月消费汇总功能。

### 技术栈
- **不做Python版本要求**: 使用系统现有Python版本
- **部署**: Docker容器化
- **输出**: PDF报告生成
- **数据库**: SQLite (.db文件)
- **运行模式**: 每日运行一次，然后挂起等待
- **数据获取**: 自动爬取银行/信用卡数据
- **通信**: 与Discord Bot项目通过数据库文件通信

## 项目架构

### 文件结构
```
~/docker/
├── token.txt                  # 全局token文件（只读访问）
├── discord_bot/
│   ├── databases/
│   │   └── discord_bot.db    # Discord Bot主数据库（FR只读访问）
│   └── [Bot项目文件]
├── FinancialReport/
│   ├── src/
│   │   ├── main.py
│   │   ├── data_processor/
│   │   │   ├── __init__.py
│   │   │   ├── account_scraper.py
│   │   │   ├── account_parser.py
│   │   │   ├── transaction_processor.py
│   │   │   └── csp_template.py
│   │   ├── report_generator/
│   │   │   ├── __init__.py
│   │   │   ├── pdf_generator.py
│   │   │   └── consumption_summary.py
│   │   └── config/
│   │       ├── config.json
│   │       └── account_configs/
│   ├── data/
│   │   ├── raw_data/          # 原始银行/信用卡数据
│   │   ├── processed/         # 处理后的统一数据
│   │   │   └── FinancialDataBaseProcessed.db  # 主数据库
│   │   └── credentials/       # 银行登录凭据(加密存储)
│   ├── output/
│   │   └── reports/          # 生成的PDF报告
│   ├── templates/
│   │   └── report_template.html
│   ├── requirements.txt
│   └── Dockerfile
├── docker-compose.yml
└── shared_volumes/
```

## 核心功能模块

### 1. 数据获取模块 (MVP核心)

#### 自动化数据爬取
- **功能**: 自动登录银行/信用卡网站获取交易数据
- **认证信息**: 从 `~/docker/token.txt` 读取银行登录凭据
- **配置方式**: 所有敏感信息从token.txt读取，禁止硬编码
- **数据下载**: 自动下载最新交易记录
- **多账户支持**: 支持多个银行和信用卡账户
- **错误处理**: 爬虫失败、验证码、账户锁定等风险 (后续处理)

#### 账户数据解析器
- **功能**: 解析各个银行/信用卡账户数据
- **输入**: 各种格式的账户数据文件 (CSV, Excel, JSON等)
- **输出**: 统一的CSP结构数据
- **挑战**: 处理不统一的字段和格式

#### Chase Sapphire Preferred (CSP) 数据格式模板
- **CSP信用卡**: 家庭主要消费卡，其数据格式作为统一模板
- **模板来源**: 直接使用Chase Sapphire Preferred的导出格式
- **标准化策略**: 所有其他银行/信用卡数据都转换为CSP格式
- **字段映射**: 根据CSP的实际导出字段建立映射规则
- **格式特点**: 
  - Chase特有的交易分类系统
  - 标准的日期和金额格式
  - 商户名称和描述字段
  - 其他银行缺失的字段填充null

#### 数据统一处理
- **CSP格式为标准**: 使用Chase Sapphire Preferred的数据格式作为统一标准
- **字段映射**: 将各账户的字段映射到CSP格式
- **数据清洗**: 处理缺失值、格式错误、重复数据
- **null填充**: 不存在的字段自动填充null
- **验证**: 数据完整性和格式验证

### 2. ALP交易识别和分类

#### ALP交易筛选
- **识别规则**: 商户名称包含"ALP"字样的所有交易
- **临时分类**: 初始标记为待确认状态
- **数据输出**: 生成ALP交易列表供确认

#### 确认流程和数据同步
- **每日启动流程**:
  1. 检查昨日pending_alp_transactions vs Discord Bot的toy_balance表
  2. 根据toy_balance表的is_toy_fund字段：
     - true: 移动到transactions表的Ginbo分类
     - false: 移动到transactions表的Family分类
  3. 清空pending_alp_transactions表
  4. 爬取新数据，识别新的ALP交易
  5. 将新的ALP交易写入pending_alp_transactions表
  6. 生成FinancialReport.pdf
  7. 挂起等待下次运行

- **数据时序**: FR项目的数据总是比实际晚一天
  - 用户今天看到的是昨天处理好的数据
  - 今天的新数据需要明天才能在报告中看到

#### Discord Bot通信
- **数据库结构**:
```
-- FinancialDataBaseProcessed.db 主表
CREATE TABLE transactions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    transaction_id TEXT UNIQUE,
    account_name TEXT,
    date DATE,
    amount REAL,
    merchant TEXT,
    description TEXT,
    category TEXT,              -- Family/Ginbo/其他分类
    is_alp BOOLEAN DEFAULT FALSE,
    status TEXT DEFAULT 'processed',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 待确认ALP交易表
CREATE TABLE pending_alp_transactions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    transaction_id TEXT,
    date DATE,
    amount REAL,
    merchant TEXT,
    description TEXT,
    status TEXT DEFAULT 'pending',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 策略追踪表 (为后续功能预留)
CREATE TABLE strategy_tracking (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    strategy_name TEXT,
    strategy_data JSON,
    last_updated TIMESTAMP,
    status TEXT DEFAULT 'active'
);
```

#### 跨项目数据访问
- **权限模型**: 
  - FinancialReport: 对自己的FinancialDataBaseProcessed.db读写
  - FinancialReport: 对Discord Bot的discord_bot.db只读
  - Discord Bot: 对FinancialReport的数据库只读
- **数据同步**: FR项目通过读取Bot的toy_balance表来决定数据分类
- **访问路径**: 
  - FR访问Bot: `/external/discord_bot/discord_bot.db`（Docker挂载路径）
- **SQLite只读访问**: 
  - 连接字符串添加`?mode=ro`参数
  - 实现重试机制处理数据库锁
  - 访问超时设置为2秒

### 3. 消费汇总报告生成

#### 数据聚合
- **按分类汇总**: 根据消费类别统计金额
- **按账户汇总**: 各个账户的消费情况
- **按时间汇总**: 日/周/月消费趋势
- **特殊分类**: Ginbo (toy_fund) vs Family消费对比

#### PDF报告生成
- **模板系统**: 使用HTML模板生成PDF
- **图表集成**: 消费分布饼图、趋势线图
- **数据表格**: 详细的消费明细表
- **统计摘要**: 关键指标和对比数据

## Docker配置

### 容器挂载
```
volumes:
  # 访问Discord Bot的数据库（只读）
  - ../discord_bot/databases:/external/discord_bot:ro
  # 访问全局token文件（只读）
  - ../token.txt:/app/token.txt:ro
  # 数据持久化
  - ./data:/app/data
  - ./output:/app/output
```

### 环境变量
- DB_PATH: 数据库文件路径
- BOT_DB_PATH: Discord Bot数据库路径（只读）
- TOKEN_PATH: token文件路径
- REPORT_OUTPUT_PATH: PDF输出路径

## 开发优先级

### MVP版本 (Phase 1): 本月消费汇总
1. **基础架构搭建**: Docker环境、Python框架
2. **CSP格式分析**: 分析Chase Sapphire Preferred的导出格式作为标准模板
3. **自动化数据获取**: 银行/信用卡数据爬取系统
4. **数据解析器**: 支持主要银行/信用卡格式，统一转换为CSP格式
5. **ALP交易识别**: 自动筛选和标记ALP交易
6. **数据库通信**: 实现与Discord Bot的只读数据访问
7. **基础PDF生成**: 简单的消费汇总报告
8. **运行调度**: 每日运行机制和挂起等待

### Phase 2: 市场情绪模块
1. 市场数据接口集成
2. 情绪分析算法
3. 市场指标计算

### Phase 3: 今日涨跌模块
1. 实时价格数据获取
2. 投资组合涨跌计算
3. 可视化图表生成

### Phase 4: 策略追踪模块
1. 与Discord Bot策略回测集成
2. 策略表现追踪
3. 验证数据分析

## 数据源和接口

### 银行/信用卡数据源
- **格式支持**: CSV, Excel, JSON, XML
- **常见银行**: 需要适配主要银行的导出格式
- **自动化**: 预留API接口用于后续自动化数据获取

### 配置管理
- **账户配置**: 每个账户的字段映射配置
- **分类规则**: 消费类别自动分类规则
- **报告配置**: PDF报告的样式和内容配置
- **Token管理**: 从~/docker/token.txt统一读取

## 鲁棒性设计

### 错误处理
- **数据格式错误**: 优雅处理未知格式，记录错误日志
- **数据库访问冲突**: SQLite只读模式，重试机制
- **PDF生成失败**: 备用简化版本报告
- **外部依赖故障**: 离线模式和缓存机制

### 数据完整性
- **事务处理**: 确保数据一致性
- **备份机制**: 定期备份处理后的数据
- **版本控制**: 数据变更历史记录
- **校验机制**: 数据完整性检查

### 性能优化
- **增量处理**: 只处理新增/变更数据
- **并行处理**: 多账户数据并行解析
- **缓存策略**: 重复计算结果缓存
- **内存管理**: 大数据集分批处理

## 部署要求

### Docker配置
- **基础镜像**: Python-slim
- **依赖管理**: requirements.txt
- **环境变量**: 配置文件路径、数据库位置
- **卷挂载**: 数据目录、共享目录、输出目录

### 定时任务
- **数据处理**: 每日自动处理新数据
- **报告生成**: 每日生成FinancialReport.pdf
- **数据清理**: 定期清理临时数据和旧报告

### 监控和日志
- **处理日志**: 详细的数据处理过程记录
- **错误日志**: 异常情况和错误信息
- **性能监控**: 处理时间和资源使用
- **通信日志**: 与Discord Bot的交互记录

## 成功标准

### 功能完整性
- [ ] 成功解析至少3种不同银行的数据格式
- [ ] ALP交易100%正确识别和分类
- [ ] 与Discord Bot通信机制稳定工作
- [ ] PDF报告生成成功率99%以上

### 数据准确性
- [ ] 消费金额计算误差 < 0.01%
- [ ] 数据分类准确率 > 95%
- [ ] 无重复或遗漏交易记录
- [ ] 与原始数据完全可追溯

### 性能要求
- [ ] 单月数据处理时间 < 30秒
- [ ] PDF报告生成时间 < 10秒
- [ ] 支持同时处理10个账户数据
- [ ] 内存使用 < 512MB

### 可靠性指标
- [ ] 7x24小时稳定运行
- [ ] 数据库访问冲突自动恢复
- [ ] 异常情况下数据零丢失
- [ ] 通信故障后自动重试成功