# AWS 账单工具配置指南

## 概述

AWS统一账单分析和导出工具支持通过配置文件进行灵活配置，特别是对错位生产账户的管理。

## 配置文件位置

两个工具程序都会按以下顺序查找配置文件：
1. 命令行参数指定的配置文件 (`--config path/to/config.json`)
2. `aws/config.json` (推荐位置)
3. `config.json` (执行目录)
4. 程序所在目录的 `config.json`

如果所有位置都没有找到配置文件，程序将使用默认配置运行。

## 账户数据集映射（aws_account_details.csv）

### 背景
账户所在的 BigQuery dataset 与表名统一写入 `aws_account_details.csv`，不再在配置文件中单独维护。

### CSV 字段

- **dataset_name**: 账户所在的 BigQuery dataset
- **table_name**: 账单表名；留空则默认 `{account_id}_aws_billing_data`

### 示例

```csv
account_id,account_name,owner_email,management_id,environment,is_shared_dev_account,dataset_name,table_name
143458967504,dbaas-prod-dataplane-000,foo@pingcap.com,bar,prod,,gcp-digital-bi.aws_prod_billing,143458967504_aws_billing_data
557537366020,dbaas-prod-clinic,foo@pingcap.com,bar,prod,,gcp-digital-bi.aws_nonprod_billing_native,557537366020_aws_billing_data
```

## 配置管理最佳实践

### 1. 版本控制
- 将配置文件加入版本控制
- 在修改前备份当前配置
- 记录配置变更的原因和时间

### 2. 环境隔离
- 开发/测试/生产环境使用不同的配置文件
- 避免在生产环境中意外使用测试配置

### 3. 配置验证
- 在部署前验证配置文件的JSON格式
- 测试新配置对现有数据处理的影响

### 4. 权限管理
- 限制配置文件的修改权限
- 建立配置变更的审批流程

## 导出目录

### 目录结构
所有环境的导出 CSV 会集中存放在同一个目录中，通过文件前缀区分环境：

```
aws/
├── aws_billing_exports/              # 所有环境导出目录
│   ├── aws_{account_id}_{year_month}.csv
│   ├── aws_prod_{account_id}_{year_month}.csv
│   └── aws_shared_{account_id}_{year_month}.csv
```

### 文件命名规则
- **非生产账户**: `aws_{account_id}_{year_month}.csv`
- **正常生产账户**: `aws_prod_{account_id}_{year_month}.csv`
- **共享测试账户**: `aws_shared_{account_id}_{year_month}.csv`

### 自定义目录配置
可以通过配置文件自定义导出目录：

```json
{
  "export_settings": {
    "outputDir": "custom/aws_billing_exports"
  }
}
```

## AWS CUR 2.0 数据切换

从 2025-10-01 起，默认使用 `aws_billing_no_payer` 的月表作为导出数据源。可通过配置调整：

```json
{
  "settings": {
    "awsBillingCutoverDate": "2025-10-01",
    "awsBillingNoPayerDataset": "gcp-digital-bi.aws_billing_no_payer",
    "awsCur2ProductField": "product_servicecode",
    "awsCur2RegionField": "product_region_code"
  }
}
```

## 费用类型过滤

可通过 `line_item_line_item_type` 控制导出范围：

```json
{
  "settings": {
    "awsLineItemTypeInclude": ["Usage", "SavingsPlanCoveredUsage"],
    "awsLineItemTypeExclude": ["Tax", "Credit", "Refund", "Fee", "RIFee", "SavingsPlanNegation"]
  }
}
```

- 当 `awsLineItemTypeInclude` 有值时，仅保留这些类型。
- 未设置 include 时才使用 exclude 进行排除。

## 调整账户数据集

当发现新的错位账户时，按以下步骤操作：

1. **识别账户**: 确认账户ID和其真实环境类型
2. **更新CSV**: 在 `aws_account_details.csv` 中设置 `dataset_name`（必要时设置 `table_name`）
3. **测试验证**: 在测试环境中验证配置正确性
4. **部署应用**: 将配置部署到生产环境
5. **监控效果**: 观察账户是否按预期环境进行处理
6. **验证目录**: 确认数据被正确保存到统一导出目录

## 注意事项

如需调整账户数据源：

1. 确认 `dataset_name` 指向正确的 BigQuery dataset
2. 如需特定表名，填写 `table_name`
3. 程序会按 `environment` 字段处理该账户

## 故障排除

### 常见问题

1. **配置不生效**
   - 检查配置文件路径是否正确
   - 验证JSON格式是否有效
   - 查看程序启动日志中的配置加载信息

2. **账户仍按错误环境处理**
   - 确认账户ID是否正确
   - 检查`enabled`字段是否为`true`
   - 验证`target_environment`字段设置

3. **数据查询失败**
   - 确认BigQuery权限设置
   - 检查数据集和表名是否存在
   - 查看程序错误日志

### 调试技巧

- 使用`--dry-run`参数进行测试运行
- 查看程序启动时的配置加载日志
- 使用`--account-id`参数测试单个账户

## 相关命令

```bash
# 查看当前配置文件内容
cat aws/config.json

# 验证JSON格式
python -m json.tool aws/config.json

# 测试特定账户处理
python aws_unified_billing_export.py --env prod --account-id 632330501419 --dry-run

# 刷新账户缓存
python aws_unified_billing_export.py --refresh-cache
```