# AWS账单管理系统重构说明

## 重构概述

原有的AWS账单管理系统已经重构为模块化架构，提高了代码的可维护性、可扩展性和可测试性。

## 新架构结构

```
aws/
├── src/                     # 核心源代码（模块化设计）
│   ├── common/             # 公共模块（配置、缓存、工具函数）
│   ├── data/              # 数据层（BigQuery、CSV处理、数据模型）
│   ├── export/            # 导出功能模块
│   ├── analysis/          # 分析功能模块（异常检测、基线计算）
│   └── notification/      # 通知模块（飞书通知）
├── main_export.py         # 数据导出程序入口
├── main_analyze.py        # 数据分析程序入口
└── legacy/               # 归档的原有程序
    ├── aws_unified_billing_export.py    # 原导出程序
    └── aws_unified_daily_analyzer.py    # 原分析程序
```

## 主要改进

### 1. 模块化设计
- **分离关注点**: 每个模块专注于特定功能
- **可重用性**: 模块可在不同场景下重用
- **易于测试**: 独立模块更容易进行单元测试

### 2. 配置管理
- 统一的配置管理器 (`src/common/config.py`)
- 支持多级配置（默认配置 + 文件配置）
- 自动查找配置文件

### 3. 错误处理和日志
- 统一的错误处理机制
- 详细的进度反馈和状态输出
- 干净的命令行参数解析

### 4. 性能优化
- 缓存管理器减少重复查询
- 并发处理提高效率
- 增量数据处理

## 程序使用说明

### 数据导出

```bash
# 基本用法
python -m aws.main_export --help

# 导出示例
python -m aws.main_export --last-week                           # 导出所有环境最近一周数据
python -m aws.main_export --env nonprod --days 30              # 只导出非生产环境最近30天
python -m aws.main_export --env prod --start-date 2025-04-01 --end-date 2025-08-20

# 测试模式
python -m aws.main_export --dry-run --days 1                   # 验证参数但不执行导出
```

### 数据分析

```bash
# 基本用法
python -m aws.main_analyze --help

# 分析示例
python -m aws.main_analyze                                      # 分析前天的所有环境数据
python -m aws.main_analyze --date 2025-08-20                    # 分析指定日期的所有环境
python -m aws.main_analyze --env nonprod --dry-run              # 仅分析非生产环境不发送通知
python -m aws.main_analyze --env prod --account-id 730335266318 # 分析指定生产账户
```

## 向后兼容性

### 数据格式兼容
- 输出的CSV文件格式与原程序完全兼容
- 配置文件格式保持不变
- 数据目录结构不变

### 功能兼容
- 支持所有原有功能
- 命令行参数基本兼容（有少量改进）
- 通知格式和内容保持一致

## 迁移指南

### 1. 替换程序调用

**原来的调用方式:**
```bash
python aws_unified_billing_export.py --last-week
python aws_unified_daily_analyzer.py --date 2025-08-18
```

**新的调用方式:**
```bash
python -m aws.main_export --last-week
python -m aws.main_analyze --date 2025-08-18
```

### 2. 配置文件
- 配置文件格式完全兼容，无需修改
- 新增了一些可选配置项，但都有合理的默认值

### 3. 脚本和自动化
- 更新CI/CD脚本中的程序调用路径
- 更新定时任务中的命令行
- 验证输出和日志格式是否符合预期

## 测试验证

### 1. 功能测试
```bash
# 测试导出功能
python -m aws.main_export --dry-run --days 1

# 测试分析功能
python -m aws.main_analyze --dry-run --env nonprod
```

### 2. 兼容性测试
- 验证输出CSV文件格式
- 验证飞书通知内容和格式
- 验证配置文件加载

### 3. 性能测试
- 对比新旧程序的执行时间
- 监控内存使用情况
- 验证并发处理效果

## 故障排除

### 常见问题

1. **模块导入错误**
   - 确保在仓库根目录执行并使用 `python -m aws.<module>` 调用
   - 检查Python环境和依赖包

2. **配置文件未找到**
   - 程序会自动查找config.json文件
   - 可以通过--config参数指定配置文件路径

3. **BigQuery连接失败**
   - 检查GOOGLE_APPLICATION_CREDENTIALS环境变量
   - 验证服务账户权限

### 调试选项
```bash
# 启用详细输出
python -m aws.main_analyze --verbose

# 启用调试模式
python -m aws.main_analyze --debug
```

## 开发说明

### 代码组织
- `src/common/`: 公共工具和配置管理
- `src/data/`: 数据访问和处理
- `src/export/`: 数据导出逻辑
- `src/analysis/`: 数据分析和异常检测
- `src/notification/`: 通知发送

### 扩展指南
- 添加新的数据源: 扩展`src/data/`模块
- 添加新的分析算法: 扩展`src/analysis/`模块
- 添加新的通知渠道: 扩展`src/notification/`模块

### 代码规范
- 使用类型提示（Type Hints）
- 遵循Python PEP 8编码规范
- 添加详细的文档字符串
- 实现适当的错误处理

## 版本信息

- **重构版本**: 2.0.0
- **重构日期**: 2025-08-26
- **兼容性**: 向后兼容1.x版本的数据和配置